Nonstop Progressive Marxism

    restable

    1.1.0 • Public • Published

    restable

    A Simple Isomorphic REST API Pattern for Express

    Build Status

    Build a server-side RESTful API that can be called directly or via http REST client.

    Install

    npm install --save restable express
    

    Usage

    The syntax for consuming your API from the client-side and server-side is identical, but it's obviously faster from the server-side because there is no http request!

    Create your API

    var restable = require('restable')
    var db = require('./db')
     
    var books = {
      get: function ($) {
        $.send({
          book: $.db.getBook($.query.id)
        })
      },
      post: function ($) {
        // $.body
        // $.query
        $.error('POST not allowed')
      }
    }
     
    var api = restable({
      resources: {
        books: books
      },
      helpers: {
        db: db
      }
    })

    Expose your API as a REST service

    var express = require('express')
    var app = express()
    app.use('/api', api.rest)
    app.listen(8080)

    Consume your API with http REST client

    var client = require('idiot')({
      baseUrl: 'http://localhost:8080/api/'
    })
     
    // GET /api/books?id=123
    client.get('books', {
      query: {
        id: 123
      }
    }, function (statusCode, data) {
      console.log('book:', data.book)
    })

    Consume your API directly (no http)

    var api = restable(opts)
     
    // GET /api/books?id=123 (but no http!)
    api.get('books', {
      query: {
        id: 123
      }
    }, function (statusCode, data) {
      console.log('book:', data.book)
    })
     
    // POST /api/books (but no http!)
    api.post('books', function (statusCode, data) {
      if (data.error) {
        console.log(data.error.message)
      }
    })

    Options

    restable(opts)

    opts

    • resources - an object whose keys are resource names
      • a resource is an object with get, post, put and/or delete methods
    • helpers - an object whose keys are helper names
      • a helper is a value that is available in all resource methods
      • i.e. passing in your db as a helper is recommended

    Your resource methods need to call either send(json) or error(message).

    var myResource = {
      get: function ($) {
        // $.myHelper
        // $.myOtherHelper
     
        // $.send(json)
        // $.send(200, json)
     
        // $.error(message)
        // $.error(obj)
        // $.error(400, message)
        // $.error(400, obj)
      }
    }

    Advanced usage

    You might have endpoints that behave differently based on the user that is calling it.

    When your endpoint is called via http, the req and res objects are available. For example, you might be using some sort of authentication middleware:

    GET /api/my/books
    var api = restable({
      resources: {
        'my/books': {
          get: function ($) {
            if (!$.req.authenticated) {
              return $.error(403, 'access denied')
            }
            $.send({
              books: []
            })
          }
        }
      }
    })
    api.rest.listen(8080)

    But oh no! This won't work if we call it from the server-side without a req object. But it's cool since we can specify req like this:

    GET /my-books.html
    // express route
    app.get('/my-books.html', function (req, res) {
      // get the books for the logged in user
      api.get('my/books', {
        req: req
      }, function (statusCode, data) {
        if (statusCode === 403) {
          return res.send(data.error.message)
        }
        res.send('You have ' + data.books.length + ' books.')
      })
    })

    Helpers

    If you're using client-sessions or bleh, this is handy:

    helpers.getUser = function () {
      var $ = this
      return $.req && $.req.session && $.req.session.user || $.user || {}
    }

    Keywords

    none

    Install

    npm i restable

    DownloadsWeekly Downloads

    13

    Version

    1.1.0

    License

    MIT

    Last publish

    Collaborators

    • will123195