soracom
SORACOM API client for Node.js.
Install
$ npm install soracom
Usage
Authenticate with a pair of email
and password
, then retrieve your operator information.
var Soracom = ;var soracom = email: 'email' password: 'password' ;soracom;
You can also specify your credentials directly on instantiation.
var Soracom = ;var soracom = apiKey: 'api_key' token: 'token' operatorId: 'operator_id';soracom
The given apiKey
and token
are automatically set to HTTP header on subsequent requests. The rest of properties, in the above case operatorId
, are used as any of default request path, query or request body.
Examples
All examples below assume that you already set the following credentials to the soracom
object.
var Soracom = ;soracom = ;soracom;
Operator
Get operator.
soracom;
Create operator.
soracom;
Subscriber
List subscribers with speed class s1.minimum
.
soracom;
Get subscriber.
soracom;
Activate subscriber.
soracom;
Deactivate subscriber.
soracom;
Insert tags to subscriber.
Note if the type of request body is an array, you cannot pass any other properties (i.e. imsi
) on the same request. To workaround this, you need to call soracom.defaults({ imsi: '123456789012345'})
beforehand, or you can just call function with static path soracom.put('/subscribers/123456789012345/tags')
).
soracom;soracom;
Delete tag from subscriber.
soracom;
API
var soracom = new Soracom(obj);
Create a Soracom
instance that can be used to make reqeusts to SORACOM's APIs.
If authenticating with user account, obj
should look like:
email: 'email@example.com' password: 'superStrongP@ssw0rd' ;
If authenticating with credentials, obj
should look like:
apiKey: 'api_key' token: 'very_long_string_token' ;
soracom.defaults(obj);
Set given object properties to either default http headers or default request path, query or request body.
If the key of property is either apiKey
or token
, then its value is set to default headers and deleted from original object. The headers are mapped like below:
headers = {
'X-Soracom-API-Key': apiKey,
'X-Soracom-Token': token
};
soracom.get(path, [params], callback);
GET any of the REST API endpints.
path
The endpoint to hit. When path contains special tag starts with :
, then that tag should be treated as variable. If there is property with same name as that variable existed in the given param, then the tag is replaced with that value.
Example 1:
var soracom = apiKey: 'api_key' token: 'token' operatorId: 'OP1234567890' ;soracom;// The operatorId is exracted from default params, so the endpoint will be "/operators/OP1234567890"
Example 2:
var soracom = apiKey: 'api_key' token: 'token' ;soracom;// The imsi is exracted from given params in a same function call, so the endpoint will be "/subscribers/123456789012345"
params
(Optional) parameters for request.
callback
The callback argument gets 3 arguments function (error, response, body)
:
error
: Anerror
object when applicableresponse
: Anhttp.IncomingMessage
objectbody
:JSON.parse()
ed response body
soracom.post(path, [params], callback);
Same as get()
, but set method to POST
.
soracom.put(path, [params], callback);
Same as get()
, but set method to PUT
.
soracom.delete(path, [params], callback);
Same as get()
, but set method to DELETE
.
Testing
Currently we have two test scripts, helper.js
and e2e.js
. helper.js
is an unit test for lib/helper.js
while e2e.js
is an integration test using lib/soracom.js
to execute real API access. By default e2e.js
is disabled (it's simply marked as skip
by mocha).
To run the unit test:
$ npm test
You can also run integration test by modifying the line in e2e.js
.
describe
Then add your accout info to test/account.json
.
$ echo '{"email": "email_address", "password": "password"}' > test/account.json
Finally run the test command, same as unit test.
$ npm test
License
MIT