API design

API design

Each version of the API is in its own Node.js module. Each API is a Node.js module within the version module.

Each operation in the API is an function in the API module. The functions are asynchronous, running a Promise and not taking a callback.

Parameters

Required parameters become positional parameters in the ECMAScript function, in the order they are listed in the Sierra API interactive documentation.

Optional parameters become attributes of an optional final object in the ECMAScript function.

A JSON body parameter is surfaced as parameters in the ECMAScript function, where is each top-level attribute of the JSON body parameter becomes a parameter of the ECMAScript function. Required attributes of the JSON body parameter become positional parameters, after all other positional parameters. Optional attributes of the JSON body parameter become additional attributes of the optional final object.

Parameters that take a comma-delimited list can be passed either a string containing the comma-delimited list or an array of strings, which will be joined into a comma-delimited list.

Responses

If Sierra responds with a 2xx status code, the Promise is fulfilled with an object being the JSON parsed from the response body.

If Sierra responds with a non-2xx status code, the Promise is rejected. This includes attempts to redirect the HTTP request.

Examples

Example: GET /v4/patrons/find Get a patron by barcode

This API endpoint has a required barcode parameter and an optional fields parameter.

The ECMAScript function of this is:

async function getPatronByBarcode(barcode, { fields } = {}) { /* … */ }

It can be called in the following ways (assuming this is in the body of an async function).

const sierraAPI = require('@sydneyunilibrary/sierra-api-as-promised').v4
let patron
// The optional fields parameter is not given.
patron = async sierraAPI.patrons.getPatronByBarcode('12345') 
// The optional fields parameter is given as a string.  
patron = async sierraAPI.patrons.getPatronByBarcode('12345', { fields: 'id,expirationDate,birthDate' })
// The optional fields parameter is given as an array.
patron = async sierraAPI.patrons.getPatronByBarcode('12345', { fields: [ 'id', 'expirationDate', 'birthDate' ] })

Example: GET /v4/patrons/metadata Get metadata list

This operation has no required parameters, but does have the two optional parameters: fields and language.

The ECMAScript function for this is:

async function getPatronByBarcode({ fields, language } = {}) { /* … */ }

It can be called in the following ways (assuming this is in the body of an async function).

const sierraAPI = require('@sydneyunilibrary/sierra-api-as-promised').v4
let metadataArray
// Neither optional parameter is given.
metadataArray = async sierraAPI.patrons.getMetadata()
// The optional fields parameter is given as an array, but the language parameter is not.  
metadataArray = async sierraAPI.patrons.getMetadata({ fields: [ 'patronType' ] })
// The optional fields parameter is not given, but the language parameter is given.
metadataArray = async sierraAPI.patrons.getMetadata({ language: 'zh-Hans' })
// The both optional fields parameter are given. The following two lines are equivalent.
metadataArray = async sierraAPI.patrons.getMetadata({ fields: [ 'patronType' ], language: 'zh-Hans' })
metadataArray = async sierraAPI.patrons.getMetadata({ language: 'zh-Hans', fields: [ 'patronType' ]  })

Example: POST /v4/patrons/{id}/holds/requests Place a new hold request

This operation has a required id parameter, and also has a JSON body parameter. The JSON body parameter has the required attributes of recordType, recordNumber and pickupLocation; as well as the optional attributes of neededBy and numberOfCopies.

The ECMAScript function for this is:

async function placeHold(id, recordType, recordNumber, pickupLocation, { neededBy, numberOfCopies } = {}) { /* … */ }

Notice that the required attributes on the JSON body parameter have become positional parameters of the function, and the that the optional attributes on the JSON body parameter have become attributes on the optional final object parameter of the function.

Example: POST /v4/patrons/ Create a patron record

This operation only has a JSON body parameter. The JSON body parameter is complex, with arrays and sub-objects. The attributes still become parameters of the function, but the parameter values will not simply be strings.

The ECMAScript function for this is:

async function createPatron({ emails, names, adddresses, phones, pin, barcodes, patronType, expirationDate, birthDate, patronCodes, blockInfo, uniqueIds } = {}) { /* … */ }

Here is an example of how to call it:

const sierraAPI = require('@sydneyunilibrary/sierra-api-as-promised').v4
let patronLink = await sierraAPI.patrons.createPatron({
  emails: [ 'jsmith@my.edu', 'john.smith@example.com' ],
  names: [ 'John Smith' ],
  addreses: [
    {
      lines: [ '1 Home Ave', 'Plesentville' ],
      type: 'h'
    },
    {
      lines: [ '100 Corporate Lane', 'Econoville' ],
      type: 'a'
    },
  ],
  phones: [
    { number: '555-123-4567', type: 'p' },
  ],
  pin: '1111',
  barcodes: [ '0987654321' ],
  patronType: 34,
  expirationDate: '2018-01-01',
  birthDate: '1969-12-31',
  patronCodes: { pcode1: 'a', pcode2: 'b', pcode3: 3 },
  blockInfo: { code: 'm' }
})