rest-spec

0.0.1 • Public • Published

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.

Readme

Keywords

none

Package Sidebar

Install

npm i rest-spec

Weekly Downloads

0

Version

0.0.1

License

none

Last publish

Collaborators

  • theroman