okanjo
v5.1.0
Published
Integrate your application with the Okanjo API.
Downloads
17
Readme
Okanjo API – JavaScript SDK
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
Breaking Changes
v5.0.0
- Supports Node.js v12+
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 optionsoptions.provider
– The communication provider class to use. Defaults toHttpProvider
for Node.js applications andFetchProvider
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 to30000
(30s).options.userAgent
– The user agent to identify as. Defaults tookanjo-nodejs/<sdk-version>
.options[api]
– Configuration options for a particular api. Useapi
for core okanjo api,farm
orshortcodes
.options[api].protocol
– The communication protocol to use, eitherhttp
orhttps
. Defaults tohttps
.options[api].host
– The remote host to use. Defaults toapi2.okanjo.com
(live).options[api].port
– The remote port to use. Defaults to443
.
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 toPOST
.
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.