api-resource
v1.0.12
Published
Simple HTTP resource wrapper
Downloads
33
Readme
API Resource
Simple wrapper for http resources for client-side JavaScript or Node.js
Setup
npm install api-resource
Simple usage
var Resource = require('api-resource');
var listUsers = new Resource({
method: 'get',
route: 'http://localhost/users/:group',
}),
createUser: new Resource({
method: 'post',
route: 'http://localhost/users',
});
// Fires GET request to http://localhost/users/followers?q=foo
listUsers.query({ // Request payload + route variables
group: 'followers'
}, { // Query params
q: 'foo'
})
.then(function (res) {
// Response code was successful (<= 200)
var results = res.body;
}, function (res) {
// Response code was not successful (> 200)
throw new Error('Users list responded ' + res.status + ', ' + res.body);
})
// Fires GET request to http://localhost/users/followers?q=foo
createUser.query({ // Request payload + route variables
username: 'johndoe'
})
.then(function (res) {
var response = res;
});
Middleware example
var Resource = require('api-resource'),
token = 'arbitrary-auth-token',
session;
var sessionEndpoint = new Resource({
method: 'get',
route: 'http://localhost/session'
});
sessionEndpoint.use(function (req, next) {
// Always add authorisation header to this resource
req.setRequestHeader('Authorization', token);
// Bind a callback to an event on this resource
this.once('success', function (res) {
console.log('Session received correctly');
});
});
sessionEndpoint.query()
.then(function (res) {
session = res.body;
});
Resource
Resource instances are also event-emitters. After querying them you can listen you can handle responses by using the promised form or by binding callbacks to their events.
Options
method
(String) Case insensitive HTTP method (E.g.'post'
)route
(String) Dynamic resource route (E.g.'http://www.foo.bar/users/:username'
)
Events
response
Fired when a response is received, with a response object passed as argumentsuccess
Fired when a successful response (Status <= 200) is received, with a response object passed as argumentfailure
Fired when a unsuccessful response (Status > 200) is received, with a response object passed as argumenterror
Fired when an error occurs sending the XMLHttpRequest, with the error passed as argument
Methods
.query([ data ], [ query_params ])
Query endpoint. The values in the data
object will also be used to build the URL if the resource route is dynamic. Query params will be added to the final URL as a query string.
.use(middleware)
Add a middleware function to the resource. The function will be called on the Resource
instance and receive as arguments the XMLHttpRequest
request instance and the next
function to proceed.
Test
Tests are currently written on server-side only. Run npm install
and npm test
to test.
Contribution
Contributions are welcome as long as documented and tested.
License
Copyright (c) 2014 Kano Computing Ltd. - Released under the MIT license