A restful, CORS enabled development server - for clicking around front end Javascript projects.
Last updated 6 years ago by narf .
BSD · Repository · Original npm · Tarball · package.json
$ cnpm install headrest 
SYNC missed versions from official npm registry.


Build Status

npm install headrest

Provides a RESTful, CORS enabled webserver intended for use when developing rest-backed Javascript apps for the browser. If you want to click around in your app, create/read/update/delete objects, but not fire up an entire backend, that is what this is for.

Assumes you init your JS app with or otherwise set an api root URL from which your models build the correct URL for their resource.

You can set the apiRoot like:

headrest = require('headrest')(apiRoot: '/apis/', dbPath: '/tmp/gruntest.json')
# headrest is an express app


It assumes your resources have paths like:

  • for a list of resources (index), /api/rocks or nested as deep as you like - /api/rocks/ffeedc/sedimentaries and so on.
  • for a single resource, /api/rocks/ffeedc, also nested as far as you want.


Implements sessions at /api/session.

  • POST whatever you want to /api/session, you'll get a Cookie.

  • GET /api/session - HTTP 200 means you're logged in, 404 if not.

  • DELETE /api/session - removes your session record and sets your cookie to expire.

Example Gruntfile.coffee

headrest = require('headrest')(apiRoot: '/apis/', dbPath: '/tmp/gruntest.json')

module.exports = (grunt) ->


          port: 5001
          hostname: ""
          keepalive: true
          middleware: (connect, options) ->

grunt headrest

This will start the server on From a browser, you can create an object with:

var request = $.ajax({
  url: "http://localhost:5001/apis/rocks",
  dataType: "json",
  crossDomain: true,
  type: 'POST',
  data: {name: "sedimentary"}

request.done(function(d) {
  var rock = JSON.parse(d)
  console.log( rock.id )

// console output:
// > 7cf28fd544be1b7f55296c45d40538f

var request = $.ajax({
  url: "http://localhost:5001/apis/rocks/7cf28fd544be1b7f55296c45d40538f",
  dataType: "json",
  crossDomain: true,
  type: 'PUT',
  data: {name: "Igneous"}

request.done(function(d) {

var request = $.ajax({
  url: "http://localhost:5001/apis/rocks/7cf28fd544be1b7f55296c45d40538f",
  dataType: "json",
  crossDomain: true,
  type: 'DELETE'

request.done(function(d) {


  • allow setting of session path.
  • keep each record in a separate file (next major ver, whoadb)


Fork and

npm install

npm test


cake test:watch

Or if any of this code is wack and you think there's a better way to do it, I definitely want to hear about it, no joke.

That's it!

I yanked this idea from my homie Mark's footrest.py

Current Tags

  • 0.1.2                                ...           latest (6 years ago)

5 Versions

  • 0.1.2                                ...           6 years ago
  • 0.1.1                                ...           7 years ago
  • 0.0.3                                ...           7 years ago
  • 0.0.2                                ...           7 years ago
  • 0.0.1                                ...           7 years ago
Maintainers (1)
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (4)
Dev Dependencies (8)
Dependents (0)

Copyright 2014 - 2016 © taobao.org |