Creating Simple Express RESTful API

Installation

npm i --save express-restful-api

Usage

var express = require('express'),
    app = express(),
    bodyParser = require('body-parser'),
    creator = require('express-restful-api');

app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: false }));

// register router
app.use('/', creator.router({
  mongo: process.env.MONGO_URL,
  schemas: {

    // register company model
    company: {
      name: {
        uniq: true,
        required: true,
        pattern: /^[a-zA-Z _]+$/,
        desc: "Company name",
        invalid: "Only alphabets number spaces allowed"
      },
      president: {
        type: 'instance',
        relation: 'person'
      },
      members: {
        type: 'children',
        relation: 'person'
      }
    },

    // register person model
    person: {
      name: {
        uniq: true,
        required: true,
        pattern: /^[a-zA-Z _]+$/
      },
      company: {
        type: 'parent',
        relation: 'company.members'
      },
      age: {
        type: 'number'
      }
    }
  }
}));

// create API document, if needed
creator.doc({
  "name": "RESTful API",
  "version": JSON.parse( fs.readFileSync('./package.json') ).version,
  "description": "API specification",
  "title": "API doc",
  "url" : "//express-restful-api-sample.herokuapp.com",
  "sampleUrl": "//express-restful-api-sample.herokuapp.com",
  "template": {
    "withCompare": false,
    "withGenerator": true,
    "jQueryAjaxSetup": {
      xhrFields: {
        withCredentials: true
      }
    }
  },
  "dest": __dirname + '/public/doc'
});

creator.router

We can specified parameters below

|Name |Type |Default | Description | |:--------|:-------------|:--------|:--------------------------------------------------------------------------------------------------------------------| |uniq |Boolean |false |This data will use to create ID. If multiple keys have uniq of true, ID will be ${key1}-${key2} | |required |Boolean |false |Enable or Disable to validate POST data. If the value is empty, 400 status code will be response | |type |String |'string' |POST data will be store following the type. 'string', 'number', 'date', 'children', 'parent', 'relation' can be used. | |pattern |String, RegExp|undefined|Enable or Disable to validate POST data. If the value does not match with pattern, 400 status code will be response | |relation |String |undefined|instance: The key will be have relationship with specified key. the value could be have only single value. children: The key will be have relationship with specified key. the value could be have multiple values. parent: If the model have relationship as children, The key should have as parent of ${parent model}.${key}.| |desc |String |undefined|API document use the value for description | |invalid |String |undefined|When the data is invalid, return message |

creator.router creates CRUD below

• Get instance ( GET )
• Get collection ( GET )
• Get child collection of a instance ( GET )
• Validate parameters ( GET )
• Create instance ( POST )
• Update instance ( POST )
• Delete instance ( DELETE )
• Delete collection ( DELETE )

Field control

You can specify response field by fields parameter. Each fields should be separated with comma.

// Only name, age response fields should be response
...fields=name,age

You can expand response field by expands parameter which has relation of parent or instance attribution type.

Example

Original resource fields of person

{
  "name": "sideroad",
  "company": {
    "id": "8ab3de2",
    "href": "/apis/companies/8ab3de2"
  }
}

Fetche with expands=company parameter

{
  "name": "sideroad",
  "company": {
    "id": "8ab3de2",
    "name": "FooBar",
    "establishedAt": "2017-10-01T00:00:00+09:00",
    "createdAt": "2017-10-01T00:00:00+09:00",
    "updatedAt": "2017-10-01T00:00:00+09:00"
  }
}

Fetching collection

Sorting

Your can specify sort order of collection.

• + or not specify operand sorted by parameter ascending.
• - operand sorted by parameter descending. You can specify multiple prioritized order separated with comma. Notice: operand should be encoded with URL parameter such as %2B in case of +.

// Get collection order by name asc, age desc.
...orderBy=name,-age

Filtering

type of string

You can use wildcard to get collection.

// Get collection which has name end with road
...name=*road

You can use comma to get collection as OR condition

// Get collection which value equal sideroad OR roadside
...name=sideroad,roadside

type of number or date

You can get collection filtered by range.

// Get collection which created the instance between 1, Dec and 5, Dec
...createdAt=[2015-12-01,2015-12-05]

// Get collection which has value between 10 and 20
...age=[10,20]

You can use comma to get collection as OR condition

// Get collection which value equal sideroad OR roadside
...age=10,20

creator.doc

API document will be generated. dest should be specified destination of the document. See apidoc to check other parameter

Example

express-restful-api-sample

Influences

API strongly influenced great architecture Beautiful REST + JSON APIs

Change log

14.0.0

Change Validate method from 'GET' to 'POST'

13.0.0

Change property name from schema to schemas