About
Javascript SDK for api.six.se
Usage
// for testing you can get token with:// Six._internal.authenticateWithCredentials(client_id,client_secret)var TOKEN = 'token-authenticated-in-backend' /* Six.connect(TOKEN,[endpoint]) */var session = Six /* session.subscribe(resource,callbackFn(error,data)) */var unsubscribe = session
Getting started
Installing from NPM
Install six-sdk
in project
# npm install six-sdk
Require the module as usual:
var Six = var session = Six
Installing from CDN
Global scope
When using the SDK from cdn.six.se the SDK is installed as Six
in the global scope. If there is a risk that this name will clash with some other var, you can change the name of the global by setting SIX_GLOBAL_NAMESPACE
before loading the SDK:
API
Before using the any of the methods in the SDK you must retrieve an authentication token from api.six.se (see the documentation for the API). This is usually done in some backend system and provided as an global var in the HTML document returned to the browser.
Session
All methods to retrive data from the API is attached to the Session object.
- subscribe(resource,callback(error,data,unsubsribe),body) -> unsubscribeFn
- refresh(resource,replace)
- create(resource,data) -> Promise
- update(resource,data) -> Promise
- remove(resource) -> Promise
- clearCache()
- setToken()
Create a session
To create a new session object:
var session = Six
Some of the functionality and analytics in the API requires some additional context (ie userid, entitlement groups etc).
To create a session with additional context:
var session = Six
For more information about session contexts, see the API documentation.
The session provides syntactic sugar for the common case of setting locale in the context:
var session = Six
Getting data from the API
The primary way to retrive data from api is via subscribe(resource,callbackFn)
or subscribe(resource,callbackFn,body)
The subscribe
method takes a resource (relative to the API endpoint, ie /markets/SEE
not https://api.six.se/v2/markets/SSE
), a callback function, and optionally an object. Passing an object can be used for functions in the API such as searching.
The callback function will be called anytime there is new data available for the resource from the SDK (some other component have called refresh
etc). The callback may be called more than once.
The callback can also first be called with an error object, and later with data.
The callback will be called with the arguments:
- error is provided if the request for data couldn't be fullfilled (see section on errors below)
- data the data provided by the api
- unsubscribeFn a function that, when called, unsubscribes the callback from future updates
unsubscribeFn is also returned from the subscribe
call itself
// retrive the reference data for an listing with id 848var unsubscribeFn = session
Error objects
Errors returned from the SDK methods is of the same structure as error responses from the API.
code: "AJAX_ERROR" title: "Request to endpoint failed" description: "The request failed. Check that the endpoint is valid?" details: endpoint: 'https://api.six.se/v2/'
error
All errors are sent to a 'error' subscription.
// register an error handler with the sessionsession
session-expired and setToken
To listen to when the session has expired the 'session-expired' resource can be subscribed to. The resource will be called when the api responds with a access denied. It is then possible to set a new token with the setToken method
Subscribe to session-expired and set a new token
session
Refresh token every hour
// You can set a new token any timevar ONE_HOUR = 1000 * 60 * 60
Caching
The SDK caches all resources fetched from the API, and all subscribers for the same resource will receive the same data when new data arrives.This means that multiple components on a page using the same underlying data will be kept in sync.
Data is cached until the session is destroyed (typically the next pageview) or session.clearCache()
is called.
Refreshing data
To populate the cache with new data, there is a method session.refresh(resource)
. The API will be called and all subscribers for the resource will have their callbacks called.
session
There is also a variant for when you want to replace the contents in the cache (default is to merge). Useful i CRUD scenarios when server state has been updated.
session
License
The MIT License (MIT)
Copyright (c) 2016 SIX Financial Information
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.