frick-sierra v1.2.3

Sierra API Client

Testing from the command line

Before you start

Install the dependencies

Once you cloned this repo run

npm i

This command will install the needed libraries.

Configuration

Copy config.tpl.yaml into config.yml. Fill in token and password as username and password

Testing a request

Use the request.yml to test making requests for a list of bibrecords and getting back a spreadsheet with the values.

You should be able to run npm start and have the cli run the request and download the information.

As a library

Authentication flow

Authentication can be a one shot authentication or can be setup to automatically update the inner API client with a new token every time the expiration of the token is hit.

In both cases we start by getting a reference to the ApiClient intance:

const { ApiClient } = require('frick-sierra');

We use now this detail to initialize the API Authentication:

const { SierraAuthentication } = require('frick-sierra');
const auth = new SierraAuthentication(ApiClient.instance, '<the base URL for the Sierra API>');

With one shot authentication we need only to call the authentication method:

await auth.authenticate('username', 'password');

The inner ApiClient is now authorized and will be able to make API calls.

Since the tokens will expire - by default every 3600 seconds from issue, we can setup the authentication to renew the token and update the ApiClient when the tokens expire:

auth.startAutoAuth();

This will renew the tokens 300 seconds before they expire automatically. You can change the tolerance to another value when you create the SierraAuthentication instance. For example, to renew the tokens 30 seconds before they expire you can create the instance like this:

const auth = new SierraAuthentication(ApiClient.instance, '<the base URL for the Sierra API>', 30);

When you are done and you want to stop the automatic authentication updates:

auth.stopAutoAuth();

Generate the API Client from scratch

export GENERATOR='https://generator.swagger.io/api/gen/clients/javascript'
export DOCS='https://arcade.nyarc.org/iii/sierra-api/docs'
curl -X POST -H "content-type:application/json" -d "{\"swaggerUrl\": \"${DOCS}\"}" ${GENERATOR}

The generator will return a JSON object:

{
    "code":"xxxxxxx",
    "link":"xxxxxxx"
}

The link property is a link to a ZIP file containing the client. You can now fetch the client.

wget -q -O api-client.zip https://generator.swagger.io/api/gen/download/<id>

Unzip api-client.zip in the root of this project and it will create the javascript-client folder.

Patch the generated Sierra client:

(cd javascript-client && patch -p1 < ../utils/api-client.patch)

Run:

npm i