For a long time, I've wanted a small JSON based API server that I could stand up in minutes with relationships. I decided that Node and Mongoose give me a lot of flexibility for small projects that I just want to try things out on.

I've been messing around with this stack and had a fairly large setup called express-shell that I use to make a more handrolled site using Express and Mongoose. But, express-shell focused on server rendering and there was a lot of things around sessions and mail that I didn't need for micro-services and smaller APIs.

So, I had a list of things that I wanted:

  • Quick start up
  • CLI Resource Generators
  • Support for One to One, Many to Many, and Has Many relationships (with foreign keys)
  • JSON output to match JSON API or namespaced JSON resources
  • OAuth 2 Bearer Grant Support
  • Easy (or auto) registration of public and protected resources

After a while of work, I've created api-kit and to go along with things generator-api-kit a Yeoman generator package to facilitate the creation of APIs.

Getting Started

To get started, install Yeoman and generator-api-kit:

npm install -g yo generator-api-kit

Then create a new API Kit project:

yo api-kit

This will create the boilerplate for our API project and install all the required Node modules.

Generating the Todo Resource for Todo MVC

One of the key points of API Kit was that it has to build quick JSON based APIs right from the command-line. So, to match Todo MVC, let's create a todos resource with two properties: an isComplete field which will be a boolean value and a title field which will be a string of what our user wants to do. We can now generate this using the api-kit:resource generator:

yo api-kit:resource todo isComplete:Boolean title:String

Here we are saying that we want to create a todo model with our different fields and data types.

This will create a few files for us:

  • app/models/todo.js - A Mongoose model describing our model schema
  • app/http/resources/public/todos.js - A set of Express.js routes for standard CRUD
  • app/transformers/todo.js - A Mystique transformer to map data in and out of our API

Using our API

Now, we can serve our API by running npm start.

If we use something like Postman, we can go to http://localhost:3000/api/todos and we'll see the following response back from our API:

{
  "todos": []
}

Let's create a new Todo for our app by sending the following JSON to our API as a POST to http://localhost:3000/api/todos:

{
  "todo": {
    "title": "Buy Milk",
    "isCompleted": false
  }
}

And now the server responds with:

{
  "todo": {
    "id": "56a01982f8630e7f4a771879",
    "title": "Buy Milk"
  }
}

NOTE Your id will vary

And if we make another GET request to http://localhost:3000/api/todos:

{
  "todos": [
    {
      "id": "56a01982f8630e7f4a771879",
      "title": "Buy Milk"
    }
  ]
}

What's Next

In the upcoming weeks I hope to document API Kit a bit more including:

  • Deploying to Heroku
  • Creating Related Records
  • User Authentication
  • Interacting with this data from a single page app (likely Ember.js)