Simple client for interacting with NYPL's internal data api

Usage no npm install needed!

<script type="module">
  import nyplNyplDataApiClient from 'https://cdn.skypack.dev/@nypl/nypl-data-api-client';


NYPL Data API Client

Helper lib for interacting with the (internal) NYPL Data API


Install it via npm for use inside your project:

npm i @nypl/nypl-data-api-client --save


Initialize a client (see ClientConstructorOptions):

const NyplClient = require('@nypl/nypl-data-api-client')
var client = new NyplClient({ 
  base_url: 'http://[FQDN].com/api/v0.1/',
  oauth_key: 'oauth-key',
  oauth_secret 'top-secret-oauth-secret',
  oauth_url: 'https://[fqdn]/'


See usage.md for complete documentation of Client methods and use.

(Usage doc is generated via ./node_modules/.bin/jsdoc2md lib/client.js > usage.md.)


To authenticate and fetch a bib (all GETs authenticate first, by default):

client.get('bibs/sierra-nypl/17746307').then((resp) => {
  let bib = resp.data
  console.log('Got bib: ' + bib.title)
}).catch((e) => console.error('Error authenticating or fetching bib: ', e))

To get the "Item" stream schema, which doesn't require authentication:

client.get('current-schemas/Item', { authenticate: false }).then((resp) => {
  let schema = resp.data
  // Now we can build an avro encoder by parsing the escaped "schema" prop:
  var avroType = require('avsc').parse(JSON.parse(schema.schema))

To get patron id 12345678 (note you must auth with an account that has the 'read:patron' role):

client.get('patrons/12345678').then((resp) => {
  let patron = resp.data
  if (!patron) console.error('Could not find patron')
  else {
    var pType = Object.keys(patron.fixedFields).map((key) => patron.fixedFields[key])
      .filter((fixed) => fixed.label === 'Patron Type')[0]
    var name = patron.names[0]
    var barcode = patron.barCodes[0]

    console.log('  Name: ' + name)
    console.log('  Barcode: ' + barcode)
    console.log('  Patron Type: ' + pType)

To POST a new "TestSchema" schema:

client.post('schemas/TestSchema', { name: "TestSchema", type: "record", fields: [ ... ] })
  .then((resp) => {
    if (JSON.parse(resp).data.stream !== 'TestSchema') throw Error('Error creating schema...')


A small CLI exists for common tasks.

If installed globally (i.e. npm i -g @nypl/nypl-data-api-client), it can be run as follows:


For local installs, it can be run via local node_modules:


To get help with any command run:

nypl-data-api help [command]

Note that the cli uses the following environment variables, read by default from .env:


See .env.example for a sample .env file. To specify a different .env, use the --envfile param (e.g. --envfile config/qa.env)

Schema post

Run the following to upload the content of the given jsonfile to schemas/[name]

nypl-data-api schema post [name] [jsonfile]


  1. Cut feature branch from master
  2. After review, merge to master
  3. Bump version in package.json & note changes in CHANGELOG.md
  4. git tag -a v[version]
  5. npm publish


All tests work offline with request and oauth stubs:

npm test

If you want to run the test suite against real infrastructure, you can do so as follows:

USE_CREDENTIALS=[credentials file, e.g. '.env'] npm test