@havforsk/toktlogger-api-client v1.0.0

Toktlogger API Client

The Toktlogger API client works in both the browser (with packaging tools like Webpack) and in NodeJS.

Basic usage:

const createAPIClient = require("toktlogger-api-client");

const api = createAPIClient("http://toktlogger.com");
api.activities.one({ id: "9478c221-a427-4f76-b82f-01b2fb28801a" })
    .then(activity => console.log(activity));

For the full list of methods, consult the API documentation in the file "Toktlogger API.pdf".

Options

createAPIClient also takes an object of options as its second parameter. The available options are:

• format: Either "JSON" or "CSV". Controls the format the API returns. Defaults to "JSON"

If format is "JSON", the following other options are available:

• parseJSON: Boolean telling whether or not the returned JSON should be parsed. If true, JavaScript objects will be returned in a promise, and the API response cannot be streamed. If false, the JSON will be returned as binary data which can either be streamed or taken from a promise. Defaults to false.

Otherwise, if format is "CSV", the following other options are available:

• charset: Controls the character charset of the CSV. Either "UTF-8" or "Windows-1252". Defaults to "UTF-8".
• delimiter: Controls the field delimiter of the CSV. Defaults to ";"
• recordDelimiter: Controls the record delimiter, also known as row delimiter, of the CSV. Defaults to "\r\n".

The options not affecting the chosen format will be ignored if set.

Getting the URL

All methods also have a way of getting the URL for the request. The methods have a property .url(), taking the same parameters as the method itself, but returning the URL without doing the request.

api.activities.one({ id: "9478c221-a427-4f76-b82f-01b2fb28801a" }); // Makes the request
api.activities.one.url({ id: "9478c221-a427-4f76-b82f-01b2fb28801a" }); // Returns the URL used for making the request, in this case http://toktlogger.com/api/activities/one?id=9478c221-a427-4f76-b82f-01b2fb28801a&format=json

Getting the data

The methods make requests using node-fetch, which is supposed to be a drop-in replacement for the Fetch API. They therefore return promises which resolve to Response objects, which can then be used to get the data as text, or a blob, or a stream, ... Notable exception: If the options { format: "JSON", parseJSON: true } are set, the methods return promises which resolve to the parsed JSON objects, ready for use.

Examples

Getting the data as JS objects, using { format: "JSON", parseJSON: true }

// Create the API
const api = createAPIClient("http://toktlogger.com");

// Make the request
api.activities.inPeriod({ after: somePastTimestamp, before: new Date() })
    .then(activities => {
        // `activities` is now a list of all the activities in the specified period
        console.log(activities);
    });

Getting the data as a JSON string:

// Create the API
const api = createAPIClient("http://toktlogger.com", { format: "JSON", parseJSON: false });

// Make the request
api.activities.inPeriod({ after: somePastTimestamp, before: new Date() })
    .then(res => res.text())
    .then(json => {
        // `json` is now the JSON representation of a list of all the activities in the specified period
        console.log(json);
    });

Getting the data as a CSV stream. Note that in the browser, the stream will be a ReadableStream, while in NodeJS, it will be a Readable

// Create the API
const api = createAPIClient("http://toktlogger.com", { format: "CSV" });

// Make the request
api.activities.inPeriod({ after: somePastTimestamp, before: new Date() })
    .then(res => res.body)
    .then(stream => {
        // `stream` is now a stream containing the CSV
        console.log(stream);
    });

For more info, see the Response type from the Fetch API, and node-fetch, as it is slightly different from the built-in browser fetch