Nothing's plumb meaningless

    okanjo

    4.7.0 • Public • Published

    Okanjo API – JavaScript SDK

    Build Status Coverage Status

    This library provides easy integration with the Okanjo platform.

    Installing

    Add to your project like so:

    npm install okanjo

    Note: this module requires:

    • an API key in order to access the Okanjo platform
    • an Okanjo Platform Account in order to access some API routes

    Usage

    You can use this module from Node.js or in the browser.

    const OkanjoAPI = require('okanjo'); 
    const api = new OkanjoAPI({
        key: 'YOUR_API_KEY_HERE'    // Set your API key here
    });

    If you use the SDK in the browser, be very mindful of security. Do not publish or expose API keys or account credentials to the public!

    When using in the browser, it is expected that you provide a server-side route to proxy API requests. This way, API keys, session secrets, etc can all be kept secure from the public. By default, the expected route is POST /rpc. The browser-based client will serialize the request so that the server side SDK instance can execute it directly with api._makeRequest(payload, (err, res) => { ... });.

    new OkanjoAPI([options])

    Creates a new instance of the API client.

    • options - Configuration options
      • options.provider – The communication provider class to use. Defaults to HttpProvider for Node.js applications and FetchProvider for browser-based invocation.

    HttpProvider Configuration Options

    • options.key – The API key to use on requests.
    • options.sessionToken – The session token to use on requests.
    • options.timeout – The client request timeout in milliseconds. Once elapsed, the request will be aborted. Defaults to 30000 (30s).
    • options.userAgent – The user agent to identify as. Defaults to okanjo-nodejs/<sdk-version>.
    • options[api] – Configuration options for a particular api. Use api for core okanjo api, farm or shortcodes.
      • options[api].protocol – The communication protocol to use, either http or https. Defaults to https.
      • options[api].host – The remote host to use. Defaults to api2.okanjo.com (live).
      • options[api].port – The remote port to use. Defaults to 443.

    FetchProvider/jQueryProvider Configuration Options

    • options.rpcHost – The server endpoint to proxy requests through. Defaults to /rpc.
    • options.rpcMethod – The HTTP method the to invoke. Defaults to POST.

    Common configuration options include:

    • options.onUnauthorizedResponse = (err, query) => { ... } – Fired when a response comes back 401-Unauthorized

    Making requests

    API endpoints are organized by resource.action on the client. For example:

    api.sessions.create(payload, (err, res) => {
        // err will be set if the request failed in any way
        // res will be set if the request was successful 
    });

    Here, sessions is our resource group. create is the action. The callback returns two parameters, err and res. If the request failed or any reason, err will be set. If the request was successful, res will be set. Both err and res are both the response payload from the server.

    You can also use promises:

    api.sessions.create(payload).execute().then(res => { ... }).catch(err => { ... });

    With await:

    const res = await api.sessions.create(payload).execute();

    Aborting requests

    When using the FetchProvider, you can provide a controller signal to shutdown a fetch request.

    For example:

    const controller = new AbortController();
    const signal = controller.signal;
    
    api.organizations.list({}).setOptions({ signal }).execute()
        .then(res => {
            // res completed successfully
            // (this won't fire in this example)
        })
        .catch(err => {
            // request failed or was aborted
            // in this example, err looks like this:
            /*
                err = {
                    statusCode: 503,
                    error: 'The user aborted a request.',
                    message: 'Something went wrong'
                }
             */
        })
    ;
    
    // Abort the request
    setTimeout(() => {
        controller.abort();    
    }, 100);
    

    See the Okanjo API documentation for information on what routes are available for use.

    Keywords

    Install

    npm i okanjo

    DownloadsWeekly Downloads

    95

    Version

    4.7.0

    License

    MIT

    Unpacked Size

    703 kB

    Total Files

    18

    Last publish

    Collaborators

    • okanjo