JSON spec validator for RESTful APIs
JavaScript CSS
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
lib
.gitignore
README.md
package.json

README.md

rest-spec

Request data validating library for RESTful APIs. rest-pec can validate POST/PUT/PATCH JSON data as well as GET/DELETE query string parameters using JSON schema and is easy to use with express.js. It generates endpoint documentation on the fly too.

Example

Say, we run an API for a blog. We could define our schema for a blog post like this and save it in a post.json file:

{
    "type": "object",
    "properties": {
        "title": {
            "type": "string", 
            "description": "Title of the post."
        },
        "body": {
            "type": "string",
            "description": "Text body of the post"
        },
        "tags": {
            "type": "array",
            "items": { "type": "string" },
            "uniqueItems": true,
            "description": "Post tags"
        }
    },
    "required": ["title", "body"],
    "additionalProperties": false,
    "description": "Blog post"
}

Our API code references this schema in a middleware that will return a 422 reponse with a list of errors before the main body of the endpoint is executed. The name of the schema is taken from the filename.

var express = require('express');
var RestSpec = require('rest-spec');
var schema = RestSpec.validator(__dirname); // look for spec files in current directory
var storage = require('myWickedStorage');

var app = express();

app.post('/posts', schema('post'), function(req, res, next) {
    var newPost = req.body;
    newPost = storage.posts.add(newPost, function(post) {
        res.json(newPost);
    }, function(error) {
        res.json(400, error);
    });
});

// make API documentation accessible at `/docs/` URL. 
RestSchema.explorer('/docs', app)

app.listen(3000);
console.log('Running API on port 3000');

POSTing malformed request will make API return 422 with the reason:

$ curl -XPOST -H "Content-Type: application/json" -d '{"title": "My first post", "kittens": true}' http://localhost:3000/posts

{
  "description": "Some fields failed to validate",
  "fields": [
    {
      "field": "body",
      "error": "Required."
    },
    {
      "field": "kittens",
      "error": "Extra field not allowed"
    }
  ]
}

Note the explorer bit in the api code:

RestSchema.explorer('/docs', app)

It maps dynamically generated documentation to /docs.