tnt.rest v0.1.1
TnT Rest
tnt.rest is a library to retrieve data from RESTful APIs.
Installation
Installation can be made with npm:
npm install --save tnt.restor from Git:
git clone https://github.com/tntvis/tnt.rest
cd tnt.rest
npm install
npm build-browserUsage
Example 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.
API
tnt.rest() returns a new rest instance that exposes the following methods:
prefix
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/");protocol
Specifies the protocol to be used (http by default).
domain
Specifies the domain for the URI.
var rest = tnt.rest()
.domain("rest.ensembl.org");port
Specifies the port to use for the URI.
var rest = tnt.rest()
.port(9988);call
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
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
});endpoint
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"
});parameters
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"]
});fragment
Sets an optional fragment for the URI (ie, the anchor after the "#" in a URI).
Feedback
Please, send any comments to emepyc@gmail.com. Bug reports and feature requests are welcome in the issue tracker