npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

rest-js

v1.1.3

Published

Interact with a Rest-API. Works on client and server (node.js).

Downloads

67

Readme

rest.js

Build Status

Interact with a Rest-API. Works on client (browser) and server (node.js).

Installation

$ npm install rest-js

Running tests

If not done yet you first need to install the global dependencies:

$ npm install -g jake browserify brfs istanbul

Then to run the tests do:

$ jake test

To run the test with code coverage:

$ istanbul cover jake test

By default Browser-sides tests will run in the chrome browser. You can override the browser(s) to use by providing a "browser" option containing a comma seperated list of browser executables:

$ jake test browser=chrome,firefox

To skip browser testing do:

$ jake test browser=none

Usage

var rest = require('rest-js');

var restApi = rest('https://api.github.com/', {
  crossDomain: true
});

restApi.read('users/der-On/repos', function(error, data) {
  ...
});

All methods also return a promise.

CRUD methods

restApi.read('/cats', [options, callback]); // GET -> /cats
restApi.get(/*...*/); // alias to .read

restApi.remove('/cats/10', [options, callback]); // DELETE -> /cats/10
restApi.del(/*...*/); // alias to .remove

restApi.create('/cats', [options, callback]); // POST -> /cats
restApi.post(/*...*/); // alias to .create

restApi.update('/cats/10', [options, callback]); // PUT -> /cats/10
restApi.put(/*...*/); // alias to .update

You can also send a rest-request with any available HTTP method using

restApi.request(method, path, [option, callback]);

Passing data

You can pass a data-Object within the options.

restApi.create('/cats', {
    data: { name: 'Minka', age: 4 }
}, function(error, data) {
    ...
});

Available constructor options

var restApi = rest('https://api.github.com/', {
    defaultParams: { ... }, // parameters that should be send with every request
    defaultFormat: 'json', // (default = 'json') default file format to use, will be appended as a suffix to the requested path (e.g. /cats -> /cats.json)
    defaultDataType: 'json', // (default = 'json') default expected data type
    crossDomain: false, // (default = false)
    cacheLifetime: 5000, // (default = 0) lifetime of URL based response cache in ms (only GET requests are cached). If set to 0 no caching will happen.
});

Middlewares

Middlewares or filters allow transormation or manipulation of request and response data.

They are simple callback functions that get passed two or more parameters.

The last parameter is always a callback function that needs to be called, once the filter has done it's work. If you pass an error to the callback it will be passed to the error middleware.

  • if using two parameters: request, next
  • if using three parameters: request, response, next
  • if using four parameters: error, request, response, next

Middlewares are executed in the same order they got appended. So if a previously appended middleware executes you get passed the already transformed data in the next middleware.

Example:

restApi.use(function(request, next) {
	var transformedUrl = request.url.replace('bar', 'foo');
	nexst();
});

You can add middlewares using the .use() method:

restApi.use(callback);  // add a middleware

You can also remove already appended filters:

restApi.unuse(callback); // remove a middleware

Rest auto appends the following filters already:

  1. Method-Fallback middleware that adds the '_method' URL parameter containing the method to use for the request. This is an approved convention to workaround the missing capabilities of browsers to send others then GET and POST requests.

  2. JSON Request-Data middleware that tries to stringify outgoing data to JSON if the request data type is 'json'.

  3. JSON Response-Data middleware that tries to parse incoming response data using JSON.stringify() if the expecte response data type is 'json'.

  4. Generic Error middleware that creates an error for each response with a status code >= 400. It tries to detect the error message from the response data.

Available request options

You can pass in options for each CRUD method or Rest.request(). These options are as follows:

restApi.read('/cats', {
	baseUrl: "...", // override the baseUrl passed to the Rest() constructor
	format: "json", // file format (will be attached as suffix to the URL, e.g. /cats -> /cats.json)
	query: {...}, // query object
	sort: {...}, // sort object, keys are property names and values either 'asc' or 'desc'
	limit: 10, // limit number of results, translates to the URL parameter 'limit'
	offset: 100, // skip first N results, translates to the URL parameter 'offset'
	skip: 100, // same as offset, but translates to the URL parameter 'skip'
	page: 10, // display page N of results, when using pagination, translates to the URL parameter 'page'
	perPage: 100, // display N results per page, when using pagination, translates to the URL parameter 'perPage'
	params: {...}, // all additional URL parameters to be send with the request
	headers: {...}, // additional request headers
	nocase: true, // (default = false) if true, case insensitive queries are created, translates to the URL parameter 'nocase'
	data: {...}, // data to be send with the request body (only for POST, PUT, UPDATE requests)
	forceUncached: true, // (default = true) if true a timestamp parameter will be attached to the URL to prevent agressive browser caching
	dataType: 'json', // the datatype to expect from the server, it will try to convert to this datatype. Possible values are: 'xml', 'html', 'json', 'jsonp', 'script', 'text', 'binary'
	crossDomain: true, // (default = false)
    noCache: true, // (default = false) if true the response data will not be cached, even if the request cache is enabled
}, function(error, data) {
	...
});