https://github.com/kanocomputing/js-api-resource
Simple JavaScript HTTP resource wrapper
https://github.com/kanocomputing/js-api-resource
Last synced: 8 months ago
JSON representation
Simple JavaScript HTTP resource wrapper
- Host: GitHub
- URL: https://github.com/kanocomputing/js-api-resource
- Owner: KanoComputing
- License: mit
- Created: 2014-06-20T15:11:55.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2016-09-06T15:57:57.000Z (over 9 years ago)
- Last Synced: 2024-12-14T19:19:52.728Z (over 1 year ago)
- Language: JavaScript
- Size: 14.6 KB
- Stars: 5
- Watchers: 19
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## API Resource
> Simple wrapper for http resources for client-side JavaScript or Node.js
## Setup
`npm install api-resource`
## Simple usage
```javascript
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
```javascript
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 argument
* `success` Fired when a successful response (Status <= 200) is received, with a response object passed as argument
* `failure` Fired when a unsuccessful response (Status > 200) is received, with a response object passed as argument
* `error` 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](https://github.com/KanoComputing/js-api-resource/blob/master/LICENSE)