This is a module for building HTTP API clients.
Initialize a new client.
Your client should inherit the prototype methods from this constructor and call it in your client's constructor.
Options
- baseUrl (String): base URL, should not include trailing slash
- headers (Object<String, String>, optional): defaults headers to include in every request
- type (String, optional, supports: form, json, text): default request body encoding type
- encoders (Object<String, Function>, optional): an object that maps a mime type to a function. The function should accept an object and return a Buffer.
- decoders (Object<String, Function>, optional): an object that maps a mime type to a function. The function should accept a Buffer or String (must support both) and return an object.
- tags (String[], optional): tags included in
_log
calls - timeout (Number, optional): default number of milliseconds before request is aborted
Usage
var papi = require('papi');
var util = require('util');
function GitHub(opts) {
opts = opts || {};
opts.baseUrl = 'https://api.github.com';
opts.header = { accept: 'application/vnd.github.v3+json' };
opts.timeout = 15 * 1000;
papi.Client.call(this, opts);
}
util.inherits(GitHub, papi.Client);
Make an HTTP request.
Your client should use this or the shortcut methods listed below to execute HTTP requests in your client methods.
Arguments
- request (Object): request options
- callback... (Function<request, next>, optional): middleware functions that can mutate
request.err
orrequest.res
. Callnext
without arguments to continue execution,next(err)
to break with an error, ornext(false, arguments...)
to trigger the final callback with the given arguments. - callback (Function<err, res>): request callback function.
Request
- path (String): request path, can include variable segments defined by curly braces (ex:
/user/{id}
) - method (String): request method
- headers (Object<String, String>, optional): request headers
- params (Object<String, String>, optional): sets variables in request path
- query (Object<String, String|String[]>, optional): query parameters
- body (Object|Buffer|Readable, optional): request body
- type (String, optional, supports: form, json, text): request body encoding type
- ctx (EventEmitter, optional): emit
cancel
to abort request - timeout (Number, optional): number of milliseconds before request is aborted
- tags (String[], optional): tags included in
_log
calls
There are also _get
, _head
, _post
, _put
, _delete
(_del
), _patch
,
and _options
shortcuts with the same method signature as _request
.
Usage
GitHub.prototype.gists = function(username, callback) {
var opts = {
path: '/users/{username}/gists',
params: { username: username },
};
this._get(opts, function(err, res) {
if (err) return callback(err);
callback(null, res.body);
});
};
Result
statusCode 200
body [ { url: 'https://api.github.com/gists/9458207',
...
Emit log events.
Arguments
- tags (String[]): tags associated with event
- data (optional): remaining arguments
Usage
client.on('log', function(tags) {
console.log({
tags: tags,
data: Array.prototype.slice.call(arguments, 1),
});
});;
client._log(['github', 'gist'], 'silas');
Result
{ data: [ 'silas' ], tags: [ 'debug', 'github', 'gist' ] }
Register an extension function.
Arguments
- event (String): event name
- callback (Function): function to execute at a specified point during the request
Usage
client._ext('onRequest', function(request, next) {
console.log('request', request.opts.method + ' ' + request.opts.path);
request.start = new Date();
next();
});
client._ext('onResponse', function(request, next) {
var duration = new Date() - request.start;
var statusCode = request.res ? request.res.statusCode : 'none';
console.log('response', request.opts.method, request.opts.path, statusCode, duration + 'ms');
next();
});
Result
request GET /users/{username}/gists
response GET /users/{username}/gists 200 1141ms
Register a plugin.
Arguments
- plugin (Object): plugin module
- options (Object, optional): plugin options
Usage
client._plugin(require('papi-retry'));
Shortcuts for making one-off requests.
See client request for full options list, with the exception
that path
is replaced with url
.
Request
- url (String): request url (ex:
http:https://example.org/
)
There are also get
, head
, post
, put
, delete
(del
), patch
, and
options
shortcuts with the same method signature as request
.
Usage
var papi = require('papi');
papi.get('https://api.github.com/users/silas/gists', function(err, res) {
if (err) throw err;
res.body.forEach(function(gist) {
console.log(gist.url);
});
});
/**
* Module dependencies.
*/
var papi = require('papi');
var util = require('util');
/**
* GitHub API client
*/
function GitHub(opts) {
opts = opts || {};
if (!opts.baseUrl) {
opts.baseUrl = 'https://api.github.com';
}
if (!opts.headers) {
opts.headers = {};
}
if (!opts.headers.accept) {
opts.headers.accept = 'application/vnd.github.v3+json';
}
if (!opts.headers['user-agent']) {
opts.headers['user-agent'] = 'PapiGitHub/0.1.0';
}
if (opts.tags) {
opts.tags = ['github'].concat(opts.tags);
} else {
opts.tags = ['github'];
}
if (!opts.timeout) {
opts.timeout = 60 * 1000;
}
papi.Client.call(this, opts);
if (opts.debug) {
this.on('log', console.log);
}
}
util.inherits(GitHub, papi.Client);
/**
* Get user gists
*/
GitHub.prototype.gists = function(username, callback) {
var opts = {
path: '/users/{username}/gists',
params: { username: username },
};
return this._get(opts, callback);
};
/**
* Print gists for user `silas`
*/
function main() {
var github = new GitHub({ debug: true });
github.gists('silas', function(err, res) {
if (err) throw err;
console.log('----');
res.body.forEach(function(gist) {
if (gist.description) console.log(gist.description);
});
});
}
/**
* Initialize
*/
if (require.main === module) {
main();
} else {
module.exports = GitHub;
}
This work is licensed under the MIT License (see the LICENSE file).