@digitallinguistics/api-js v0.3.0

DLx API JavaScript Client

A JavaScript client for accessing the DLx database API from the browser, using Socket.IO. This library handles connecting to the socket, retrieving an access token, and authenticating with the API, so you can quickly begin making requests without going through complicated setup.

NOTE: This library requires dlx-js as a peer dependency. Make sure you include the dlx-js library in your page before idb.

Installation

If using npm:

npm i --save @digitallinguistics/api-js

If using yarn:

yarn add @digitallinguistics/api-js

You can also include the api-js script in your page using the DLx CDN.

<script src=https://cdn.digitallinguistics.io/scripts/api-js.js></script>

Or download the script manually:

curl https://cdn.digitallinguistics.io/scripts/api.js -o api.js

The DLx Socket Client also requires dlx.js as a peer dependency. You should include it in your HTML before your api.js file:

<script src=https://cdn.digitallinguistics.io/scripts/dlx.js></script>

Including the Script on Your Page

The api-js library may be used either as a module (all module types are supported, including ES6) or a regular script. If using the library as a regular script, DLxAPI will be made available as a global variable, and the client class will be accessible on DLxAPI.default.

Using ES6 modules:

import SocketClient from './api.js';

Using CommonJS modules:

const SocketClient = require('./api.js');

As a regular script:

<script src=api.js></script>

<script>
  const SocketClient = DLxAPI.default;
</script>

Initializing the Client & Connecting to the Socket

To create a new client, simply provide your application's client ID and client secret as options, along with your redirect URI. (If you have not yet registered your application with the DLx API and received a client ID and client secret, read the API documentation for details on how to do so.)

const client = new SocketClient({
  clientId:     `6d38028e-5161-47df-8652-95d1ac8e915f`,
  clientSecret: `f36557c1-38d7-4f96-9400-95f5fce8b685`,
  redirect:     `https://mydomain.com/callback`,
});

If you already have an access token, you may provide that instead:

const client = new SocketClient({ token: `eyJhb...7HgQ` });

Once the client is initialized, call client.connect() to connect to the socket. This will return a Promise that resolves when the client is connected.

Authenticating with the API

Before you can make a request to the database, you will need to authenticate your application. This is as easy as calling the .authenticate() method, which returns a Promise when authentication is complete. If the client is not already connected to the socket, it will be connected during authentication. If you have not yet retrieved an access token, the client will attempt to retrieve one for you. This may involve your application being redirected to a user login page.

client.authenticate()
.then(() => {
  /* begin making requests */
});

Making Requests to the Database

Once you are authenticated with the API, your application may begin making requests to the database. The client has methods for each type of operation on the database. For example, each of the following methods is available for Language items:

• addLanguage()
• deleteLanguage()
• getLanguage()
• getLanguages()
• updateLanguage()
• upsertLanguage()

Each method returns a Promise that resolves to the database response.

You can also use the more generic add(), delete(), get(), getAll(), update(), and upsert() methods if you wish; however, it is recommended that you use type-specific events over generic events.

View the documentation for a complete list of methods available on the database client. (Click on Modules at the top of the page, and then SocketClient.)

If for some reason you need to emit events from the socket which aren't available as a method, you can do so using client.emit(). You can also access the web socket object at client.socket once the client is connected.

Complete documentation on using the socket API can be found here.

Events Emitted by the Socket

Each time data in the database is modified, the socket emits an event indicating the type of operation that was performed on the database, and the ID of the affected data. Your application can then decide whether it needs to make a request for the updated data. This is useful for ensuring that the data in your application stays in sync with the database.

The following events are emitted by the Socket API. Many of these events are emitted along with the ID of the affected item.

Your application should add listeners for each of these events, like so:

// this event will be emitted every time a new item is added to the database
client.on(`add`, id => {
  client.get(id, (err, res) => { /* do something with the new data */ });
});

The SocketClient also has all the standard Emitter methods:

• .emit()
• .hasListeners
• .listeners
• .off()
• .on()
• .once()

Handling Errors

You can add a generic error handler to listen for errors after the client is connected:

client.connect()
.then(() => client.on(`error`, console.error));

Otherwise, most errors will be returned in the callback function you provided when emitting an event. For example:

client.getLanguage(`12345`, (err, res) => {
  if (err) /* handle error */
  else /* do something with the response */
});

Want to Contribute?

Check out DLx's general contributing guidelines.

Maintainers

This repo is maintained by:

• Daniel W. Hieber (dhieber@umail.ucsb.edu)