JavaScript API Client for Mythradon¶

This guide provides a JavaScript module that helps developers interact with the Mythradon REST API. It supports standard HTTP methods and includes optional HMAC-based authentication.

Getting Started¶

To use the API client, you'll need the following:

Your API_KEY (required)
Your SECRET_KEY (optional, for HMAC authentication)
Your Mythradon instance URL

Install any dependencies (e.g., querystring, https) using Node.js if not already available.

Example Usage¶

Import the Client¶

const Client = require('./api-client');

Initialise the Client¶

const client = new Client(
    'https://<your-platform-domain>',
    'API_KEY',
    'SECRET_KEY' // Optional: Required only for HMAC authentication
);

POST Example – Create a New Record¶

const payload = {
    name: 'Some name',
};

client
    .request('POST', 'Account', payload)
    .then(response => {
        console.log('Created:', response);
    })
    .catch(error => {
        console.error('Error:', error.statusCode, error.statusMessage);
    });

GET Example – Query Records¶

const params = {
    maxSize: 5,
    where: [
        {
            type: 'equals',
            attribute: 'type',
            value: 'Customer',
        },
    ],
    select: ['id', 'name'],
};

client
    .request('GET', 'Account', params)
    .then(response => {
        console.log('Accounts:', response);
    })
    .catch(error => {
        console.error('Error:', error.statusCode, error.statusMessage);
    });

The `api-client.js` Module¶

This module handles API requests, authentication, error handling, and JSON parsing.

File: api-client.js:

class Client {

    /**
     * @param {string} url
     * @param {string} apiKey
     * @param {string|null} [secretKey]
     * @param {
     *   {
     *     port?: number,
     *     timeout?: number,
     *   }
     * } [options]
     */
    constructor(url, apiKey, secretKey = null, options = {}) {
        this.url = url;
        this.apiKey = apiKey;
        this.secretKey = secretKey;

        if (this.url.substr(-1) === '/') {
            this.url = this.url.substr(0, this.url.length -1);
        }

        this.options = options;

        this.urlPath = '/api/v1/';
        this.isHttps = url.toLowerCase().indexOf('https') === 0;
    }

    /**
     *
     * @param {'GET'|'POST'|'PUT'|'DELETE'|'PATCH'|'OPTIONS'} method
     * @param {string} action
     * @param {Record} [data]
     * @return {Promise}
     */
    request(method, action, data) {
        method = method || 'GET';
        method = method.toUpperCase();

        let url = this._buildUrl(action);

        const headers = {};

        if (this.apiKey && this.secretKey) {
            const crypto = require('crypto');

            const string = method + ' /' + action;

            const authString = this.apiKey + ':' +
                crypto.createHmac('sha256', this.secretKey).update(string).digest('hex');

            const authPart = Buffer.from(authString).toString('base64');

            headers['X-Hmac-Authorization'] = authPart;
        } else if (this.apiKey) {
            headers['X-Api-Key'] = this.apiKey;
        } else {
            throw new Error('Api-Key is not set.');
        }

        let postData;

        if (data) {
            if (method === 'GET') {
                const querystring = require('querystring');

                url += '?' + querystring.stringify({searchParams: JSON.stringify(data)});
            } else {
                postData = JSON.stringify(data);

                headers['Content-Type'] = 'application/json';
                headers['Content-Length'] = Buffer.byteLength(postData);
            }
        }

        return new Promise((resolve, reject) => {
            const o = {
                headers: headers,
                method: method,
            };

            if (this.options.port) {
                o.port = this.options.port;
            }

            if (this.options.timeout) {
                o.timeout = this.options.timeout;
            }

            const h = this.isHttps ? require('https') : require('http');

            const req = h.request(url, o, res => {
                let data = '';

                res.on('data', chunk => {
                    data += chunk;
                });

                res.on('end', () => {
                    if (res.statusCode < 200 || res.statusCode > 299) {
                        reject(res);

                        return;
                    }

                    try {
                        data = JSON.parse(data);
                    } catch (e) {
                        console.error(`Error: Could not parse response`);
                        reject({});

                        return;
                    }

                    resolve(data, res);
                });
            });

            req.on('error', e => {
                console.error(`Error: ${e.message}`);

                reject(e);
            });

            if (data && method !== 'GET') {
                req.write(postData);
            }

            req.end();
        });
    }

    _buildUrl(action) {
        return this.url + this.urlPath + action;
    }
}

if (module && module.exports) {
    module.exports = Client;
}

Features¶

Simple wrapper for RESTful requests
Supports GET, POST, PUT, PATCH, DELETE, and OPTIONS
Compatible with API Key and HMAC authentication
Handles errors and parses JSON responses
Optional support for custom ports and timeouts

Notes¶

The id field of each record is required for operations like update or delete.
Use the Metadata API or Entity Manager to explore available entity names and attributes.
This module is intended for server-side use with Node.js.