Elebase JavaScript Development Kit

An isomorphic API client and development kit for the Elebase platform.

Installation

NPM

npm install @elebase/sdk --save

Yarn

yarn add @elebase/sdk

Usage

This package can be used in web browsers and Node.js environments.

N.B. A module bundler such as Webpack is required for use in a web browser.

Importing the library

const ele = require('@elebase/sdk');

Creating API Client Instances

Create an instance of the Project API client:

const projectAPI = ele.api({
  key: { public: 'PUBLIC API KEY', private: 'PRIVATE API KEY' },
  locales: ['en', 'es', 'fr'],
  phases: [4],
  project: 'PROJECT ID',
  user: 'USER ID'
});

Create an instance of the Geo Tools API client:

const geoAPI = ele.geo({ token: 'API TOKEN' });

Both the ele.api() and ele.geo() functions accept an API client configuration object with the properties described in the table below.

Property | Type | Description | Required ---------|------|-------------|:--------: http | object | An HTTP client configuration object with the following optional properties: headers: an object with HTTP headers to include with each API requesttimeout: the number of milliseconds to wait before aborting an API request (default: 20000)logging: a boolean indicating whether or not verbose HTTP request/response logging should be enabled (default: false) key | object | An object with public and private API keys. These keys can be generated and retrieved from the API Keys screen of the web app. Note: API keys with POST, PUT, and/or DELETE privileges should never be exposed in client-side code. It's also good practice to never commit them to a remote code repository (even if the repository is private). Instead, the keys can be defined as environment variables and made available in server-side code via Node's process.env object using a package like dotenv. This setting is required if token is not defined. | locales | array | An array of locale codes to include in the Accept-Language header of each API request. See the Localization section of the API documentation for more details. | phases | array | An array of integers representing the phases to filter Entries by. For example, if this configuration option is set to [4], each GET /entries request will automatically include a phase parameter in the URL with a value of 4. This can be overridden on a per-request basis. For more details on the phase parameter, see the description in this table. project | string | The ID of an Elebase Project. | ✓ token | string | An API token. An API token can be generated for any existing API key via the API Keys screen of the web app. Note: API tokens with POST, PUT, and/or DELETE privileges should never be exposed in client-side code. It's also good practice to never commit them to a remote code repository (even if the repository is private). Instead, tokens can be defined as environment variables and made available in server-side code via Node's process.env object using a package like dotenv. This setting is required if key is not defined and ignored if key is defined. | user | string | The ID or authentication token of a User to include in the Authorization header of each API request. This can be overridden on a per-request basis. Note: If a request requires a User ID or token, it will be indicated in the API documentation. | version | string | The API version to target (default: v1). |

Sending API Requests

Send a request to the Project API for the first 10 published Entries when ordering by title:

(async () => {
  try {
    const options = { params: { limit: 10, order: 'title', page: '1', phase: '4' } };
    const res = await api.get('/entries', options);
    console.info(res.data.index);
  } catch (err) {
    console.error(err);
  }
})();

Send a request to the Geo Tools API for the elevation at given location:

(async () => {
  try {
    const options = { data: { geometry: { type: 'Point', coordinates: [-109.80856, 45.16372] } } };
    const res = await geoAPI.post('/elevations', options);
    console.info(`Elevation: ${Math.round(res.data.coordinates[2])} meters`);
  } catch (err) {
    console.error(err);
  }
})();

API Request Methods

Verb | Method -----|------- GET | api.get() POST | api.create() or api.post() PUT | api.update() or api.put() (Project API only) DELETE | api.delete() (Project API only)

All methods support two arguments: an API endpoint path (e.g., /entries or /measurements) and an optional Request Configuration object, which is described in the table below.

Request Configuration Object

Property | Type | Description ---------|------|------------ data | object | An object to encode as a JSON string and send in the body of the request. This setting is for POST and PUT requests only. first | boolean | If true and this is a GET request, the first object in the data.index array of the response body will be returned instead of an object with index and total properties. If the data.index array is empty, a null value will be returned. Setting this option to true is useful when only one result is expected or desired—when filtering by ID, for example. This setting is for Project API requests only. headers | object | Custom HTTP headers to include with the request. locales | array | An array of locale codes to include in the Accept-Language header of the request. See the Localization section of the API documentation for more details. This setting is for Project API requests only. params | object | A plain or URLSearchParams object containing query parameters to include in the URL of the request. user | string | The ID or authentication token of a User to include in the Authorization header of the request. Note: If a request requires a User ID or token, that requirement will be specified in the API documentation. This setting is for Project API requests only.

Handling API Responses

All API request methods return Promises that either resolve with a Response object or reject with a RequestError object. Details on both of these objects are provided below.

Response Object

Property | Type | Description ---------|------|------------ data | object/null | The JSON-decoded response body (or null if the body was empty). headers | object | The HTTP response headers. status | integer | The HTTP response status code.

Project API RequestError Object

Property | Type | Description ---------|------|------------ data | mixed | The data property from the Error object returned by the API endpoint. headers | object | Response headers relevant to the error (e.g., the X-Usage-Limit-Info and X-Usage-Limit-Time headers from a 429 response). id | string | The id property from the Error object returned by the API endpoint. message | string | A basic error message that includes the full JSON Error object returned by the API endpoint. status | integer | The status code of the response.

Geo API RequestError Object

Property | Type | Description ---------|------|------------ code | string | The code property from the Error object returned by the API endpoint. headers | object | Response headers relevant to the error (e.g., the X-Usage-Limit-Info and X-Usage-Limit-Time headers from a 429 response). info | string | The info property from the Error object returned by the API endpoint. status | integer | The status code of the response. type | string | The type property from the Error object returned by the API endpoint.

API Documentation

Full API references can be found in the Learn section of our website.

• Project API Reference
• File Tools API Reference
• Geo Tools API Reference