quickrest

A simple library for quickly building browser-based REST API clients.

This project is a WIP

Status

Features

• Offers both a callback and promise-based API.
• Bring your own Promise and request libraries.
• Makes reasonable assumptions about the structure of your REST API.
• Supports complex API versions.
• Offers a fluent API for requesting nested resources.

Simple Example

import quickrest from 'quickrest'

const api = quickrest({
  root: 'https://api.example.com',
  versions: 'v2',
  endpoints: [
    'users',
    'users/posts',
    'users/posts/comments',
    'posts',
    'posts/comments',
    'comments',
    {
      resource: 'comments',
      createMethod: 'put', // put will be used for creation and update
    }
  ],
})

// callback interface
// GET /users/9000
api.users(9000).get((err, resp) => console.log(err, resp.model))

// promise interface
// GET /users/9000
api.users(9000).get()
  .then(({model, }) => console.info(model))
  .catch(console.error.bind(console))

// get nested resource
// GET /users/9000/posts/3
api.users(9000).posts(3).get()

// get nested resource, and pass response to callback
// GET /users/9000/posts
api.users(9000).posts.list({page: 42, rpp: 200, query: 'bah'}, console.log.bind(console))

// create nested resource
// POST /users/9000/posts
api.users(9000).posts.create({title: '...', content: 'something'})

// create doubly-nested resource
// POST /users/9000/posts/3/comments
api.users(9000).posts(3).comments.create({title: '...', content: 'something'})

// delete nested resource
// DELETE /users/9000/posts/3
api.users(9000).posts(3).del()

// api versioning via url
// GET /v2/users
api.v2().users(9000).get()
  .then(({model, }) => console.info(model))
  .catch(console.error.bind(console))

// the backward-incompatible and deprecated comments API
// PUT /comments
api.comments.create({post_id: 3, data: 'something'})

// /v2/comments
api.v2().comments.create({post_id: 3, content: 'something'})

Motivation

Constructing API urls via string concatenation (or even template strings) can be annoying and error prone. Using JavaScript's language featues to model a REST API's resources makes for a more pleasant programming experience.

Caveats

The library is currently meant for environments where high-level REST parameters are set once for the lifetime of the app/process, (e.g., bearer tokens for an app) like in a browser. It lacks a simple mechanism to scope request-specific REST data (e.g., per-request data within an express.js app).

This capability is not a priority at the moment, but a PR with it is welcome =). It might look something like this:

import quickrest from 'quickrest'
const api = quickrest(...);

// and then for each request (e.g., in an express middleware function)
function(req, res, next){
  req.api = api.specialize({
    beforeEach(params, query, headers, cb){...},
    headers: {...},
  })

  next()
}

Installation

npm install quickrest --save

If you're indifferent to the http and Promise libraries used, this lib will attempt to use superagent and es6-promise, respectively. These libraries are considered peer dependencies, so it's your responsibility to install them alongside this lib.

npm install --save es6-promise superagent

Node/CommonJS

const quickrest = require('quickrest')

ES6 Module

import quickrest from 'quickrest'

Documented Example

import bluebird from 'bluebird'
import qwest from 'qwest'
import quickrest from 'quickrest'

const api = quickrest({
  /**
   * The base url for your REST API.
   * @required
   * @type {String}
   */
  root: 'https://api.example.com',

  /**
   * A prefix for all rest endpoints.
   *
   * This is optional.
   *
   * @see implemented examples below.
   * @example
   * // for only one version
   *   {
   *     versions: 'v2',
   *   }
   * @example
   * // to declare multiple versions
   *   {
   *     versions: ['v2']
   *   }
   * @type {Array|string}
   */
  versions: ['v2'], // a version prefix for all endpoints.

  /**
   * A Promise/A+ compliant Promise implementation.
   * @example RSVP.Promise, q, bluebird, etc.
   *
   * Uses [es6-promise](https://github.com/stefanpenner/es6-promise) by default.
   *
   * @type {Promise}
   */
  promise: bluebird,

  /**
   * Makes HTTP requests.  If this function is not specified, the library will use `superagent`.  superagent is a peerDependency, and it is your responsibility to install it.
   *
   * @param  {string}   url     the url to which the request will be made
   * @param  {string}   method  the http method lowercased (i.e., get, put, etc)
   * @param  {Object}   params  parameters to be sent with the request
   * @param  {Object}   [ query ]   query string parameters
   * @param  {Object}   headers headers to be sent with the request
   * @param  {Function} cb      callback invoked with the result of the http request
   * @return {Promise|null}           either a promise if the http request lib returns a promise, or null.  Alternatively, the callback `cb` may be invoked in the typical node style (i.e., cb(err, resp)).
   */
  request: (url, method, params, query, headers, cb) => {
    // since qwest returns a promise, there's no need to invoke the cb
    return qwest[method].bind(qwest, method)(url, params, headers)
  },

  /**
   * An object with the methods {log, info, warn, error}.  Defaults to a
   * noop logger if left undefined.
   * @type {Object}
   */
  logger: console,

  /**
   * Headers sent with every request.
   *
   * This is optional.
   *
   * The headers displayed below are set by default.
   *
   * @type {Object}
   */
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },

  /**
   * An mapping of REST API method names to synonyms to prevent conflicts with REST API resource names.
   * @type {Object}
   */
  altMethodNames: {
    create: 'make',
    patch: 'mend',
    del: 'remove'
    get: 'fetch',
    list: 'all',
    update: 'overhaul',
  },

  /**
   * A function run before each network request. It receives any HTTP request body and query string parameters entered by the user, in additional to consolidated headers. It should return an object containing additional params, query string, or headers that should be added to the request.
   * @param  {Object}   params  request parameters
   * @param  {Object}   query   request query string parameters
   * @param  {Object}   headers headers set by the user invoking an api function.
   * @param  {Function} cb      callback function optionally invoked
   * @return {Promise.<Object>|Object}           An object containing headers
   */
  beforeEach(params, query, headers, cb){
    // e.g., add as csrf token, authorization header, etc
    const np = {csrf: 'randomToken'}

    const nh = {Authorization: `Bearer ${token}`}

    return Promise.resolve({headers: nh, params: np})
    // or return {headers: nh, params: np} which becomes Promise.resolve(...)
    // or return cb(null, {headers: nh, params: np})
  },

  /**
   * An array of the endpoints of your REST API.
   * @type {Array}
   */
  endpoints: [
    'users',
    'users/posts',
    'users/posts/comments',
    'posts',
    'posts/comments',
    'comments',
    'posts',
    'comments',
    {
      resource: 'comments',
      createMethod: 'put', // put will be used for creation and update
      headers: {
        'X-API-VERSION': 'example.v2',
        'Accept': 'application/vnd+example.comments+json'
      }
    }
  ]
})

Development

Clone respository and install dependencies.

All development dependencies are managed via npm.

npm install

License

MIT