tnt.rest is a library to retrieve data from RESTful APIs.
Installation can be made with npm:
npm install --save tnt.rest
or from Git:
git clone https://github.com/tntvis/tnt.rest
cd tnt.rest
npm install
npm build-browserExample of usage:
<head>
<script src="build/tnt.rest.js"></script>
</head>
<body>
<div id="mydiv"></div>
<script>
var rest = tnt.rest()
.domain("rest.ensembl.org")
var url = rest.url()
.endpoint("xrefs/symbol/:species/:id")
.parameters({
"species": "human",
"id": "BRCA1",
});
rest.call(url)
.then (function (resp) {
var data = resp.body;
// use data
});
</script>
</body>See the examples folder for more examples.
tnt.rest() returns a new rest instance that exposes the following methods:
Specifies any prefix to be added to the URI. This is useful for calls that are proxy-ed through a web server that expects a given prefix in the URIs. This prefix is inserted even before the protocol
var rest = tnt.rest()
.prefix ("/proxy/");Specifies the protocol to be used (http by default).
Specifies the domain for the URI.
var rest = tnt.rest()
.domain("rest.ensembl.org");Specifies the port to use for the URI.
var rest = tnt.rest()
.port(9988);Performs a call using the provided url. By default a GET request is made. The first argument is mandatory and can be a string specifying the complete URI for the resource or a tnt.rest.url instance (see below). If the former any prefix, protocol, domain and port set via the API are ignored. If the latter those options are used to build the resource URI. If a second argument is provided and is an object a POST request is made using this object as its post data. The method returns an ES6-compliant promise that can be chained via its then method and errors are catchable via its catch method.
Example of GET request:
var rest = tnt.rest();
rest.call("http://rest.ensembl.org/xrefs/symbol/homo_sapiens/BRCA2?content-type=text/xml")
.then (function (resp) {
// do something with resp
})
.catch(function (err) {
// do something with err
})Example of POST request:
var rest = tnt.rest();
rest.call("http://rest.ensembl.org/lookup/id?content-type=application/json", {
"ids" : ["ENSG00000157764", "ENSG00000248378" ]
})
.then (function (resp) {
// do something with resp
})tnt.rest.url provides an interface to build URIs using its API. Using this API is not mandatory since you can pass directly the URI string to the call method (see above for examples).
The returned url instance exposes several methods explained below.
var rest = tnt.rest()
.endpoint("rest.ensembl.org");
var url = rest.url()
.endpoint("xrefs/symbol/:species/:id")
.parameters({
"species": "human",
"id": "BRCA1"
});
rest.call(url)
.then (function (resp) {
// do something with resp
});Specifies the path field in the URI. If the endpoint string contains arguments (ie, parts starting with a ":") they are substituted by their corresponding options in the parameters method.
var rest = tnt.rest();
var url = rest.url()
.endpoint("xrefs/symbol/:species/:id")
.parameters({
"species" : "human",
"id" : "BRCA1"
});Sets the endpoint arguments and optional parameters in the URI. It accepts an object whose properties are the name of the argument / parameter and the values their value. Array values are allowed making the parameter to be repeated as many times as items are in the array.
var rest = tnt.rest();
var url = rest.url()
.endpoint("xrefs/symbol/:species/:id")
.parameters({
"species" : "human",
"id" : "BRCA1",
"feature" : ["gene", "cds"]
});Sets an optional fragment for the URI (ie, the anchor after the "#" in a URI).
Please, send any comments to emepyc@gmail.com. Bug reports and feature requests are welcome in the issue tracker