Install
npm i shooju-client --save
Connect
- Create an API Key on the My Profile (under your name on the top-right of the website) page by using Create New API Key.
- Make note of the server (the url of the Shooju instance you log in to), username (it's on the top of the My Profile page)
- Instantiate a Shooju Client:
var shoojuClient = require("shooju-client");
var sjclient = new shoojuClient('http(s)-prefixed shooju url', 'my-username', 'my-api-key');
Read from Shooju
The Javascript client exposes raw get/post requests using the raw.get(url, dict of url params, success(data), error(data))
and raw.post(url, dict of url params, dict of post json, success(data), error(data))
functions.
Option 1. Retrieve 1+ Series using one Queries:
sjclient.raw.get('/series',
{ query:'sid:my\\series\\query*', fields:['description'], df:'MAX', dt:'-4w', max_points:-1 },
function(response) {
// success callback
}, function(error) {
// error callback
});
Option 2. Retrieve 1+ Series using single queries, one for each series.
sjclient.raw.post('/series', {
'fields': 'l2'
}, {
'series': [
{
'query': 'sid=test\\1',
'fields': 'l1,l2'
},
{
'query': 'sid=test\\2'
}
]
}, function(response) {
// success callback
}, function(error) {
// error callback
});
Option 3. Retrieve 1+ Series using one query, scrolling over a large number of results without paginating:
sjclient.scroll({
query: '', //required
//all parameters below are optional:
fields: '',
df: '', //default: MIN
dt: '', //default: MAX
max_points: 0, //default: 0
sort: '', //default: sid asc
max_series: 300, //default: no limit; after reaching this number of series, scrolling stops
scroll_batch_size: 1000, //default: 1000
extra_params: {
//passed directly to the Shooju /series API
}
},
series_callback(series){
//called for each series; series object is the Shooju series with attributes:
// series_id, fields, points
},
error_callback(error){
//called on any API error; error object is the Shooju error response with attributes:
// error, request_id, (description)
},
finish_callback(){
//called upon successful finish (is not called if error_callback is invoked)
//also called if no series are returned (this is a success, not an error)
}
)
Write to Shooju
Instantiate a job and write a field to a Series :
sjclient.raw.post('/jobs', {}, { description: 'my job description', source: 'my job source', notes: 'my job notes' }, function(jobStartResponse) {
sjclient.raw.post('/series/write', { job_id: jobStartResponse.job_id }, {
series: [{
series_id: 'users\\myusername\\test\\a',
fields: {'description': 'my favorite series'}
}]
}, function(response) {
sjclient.raw.post('/jobs/' + jobStartResponse.job_id + '/finish', {}, {}, function(jobCompleteResponse) {
// success callback
});
});
});