This package has been deprecated

Author message:

Unmaintained, please use npmjs.com/api-i

Create REST API

v.5.1.1

Unmaintained, please use api-i

Create your REST API from scarch

• Dependencies

• Instalation

• Simple Usage Example

• Start API server

• Searching

• Filters and orders

• HATEOAS

• Linked Usage Example

• Error examples

• Change Log

Dependencies

• Node.js v.4.0 or higher

• MongoDB

Instalation

npm install --save create-rest-api

Simple Usage Example

// index.js
var Api = require('create-rest-api');
var api = new Api();
 
api.model('writers');
 
api.start();

Token Usage Example

use test
db.users.insert({ login: 'admin', password: '21232f297a57a5a743894a0e4a801fc3', group: 'admin', name: 'Administrator' });

const Api = require('create-rest-api');
const api = new Api({
  token: {
    secret: '⟶Sǝcяeť✙', // token's secret, required
    expire: 60 * 10,    // 10 minutes token expired, not required, default is 1 minute
  },
});
 
api.model('comments');  // /comments are free to anyone
 
api.needToken();        // after that etheryfing will be checked for token ( X-Access-Token in headers, use /login to get one )
 
api.model('movies', {   // for login store use /my/{login}/movies, for group store - /our/{group}/movies, others - /movies
  stars: { link: 'stars' },
});
 
api.model('stars');     // for login store use /my/{login}/stars, for group store - /our/{group}/stars, others - /stars
 
api.start();

; get new token
curl -X POST -H "Content-Type: application/json" -d '{"login":"admin","password":"admin"}' 127.0.0.1:8877/login
; > {"token":"{TOKEN}","login":"admin","group":"admin","name":"Administrator"}
 
; add movie owner by login:admin
curl -X POST -H "X-Access-Token: {TOKEN}" -H "Content-Type: application/json" -d '{"name":"Movie 1 admin login"}' 127.0.0.1:8877/my/admin/movies
 
; get login:admin owner movies
curl -H "X-Access-Token: {TOKEN}" 127.0.0.1:8877/my/admin/movies
 
; renew token
curl -X PATCH -H "X-Access-Token: {TOKEN}" 127.0.0.1:8877/login

Usage Example with validation

// index.js
var Api = require('create-rest-api');
var api = new Api(null, {validation: true});
 
api.model('writers', {
  name: { type: 'string', required: true },
  sex: { type: 'any', one: ['M', 'F'] }
});
 
api.start();

Methods

Method	URL	Description	Response	Posible errors
GET	/writers	List of writers	200 OK	404 NOT_FOUND
GET	/writers/{id}	Single writer info	200 OK	404 NOT_FOUND
POST	/writers	Add new writer	201 CREATED	400 DATA_VALIDATION_ERROR
PUT	/writers/{id}	Update some writer's information	200 OK	400 DATA_VALIDATION_ERROR, 404: NOT_FOUND
PATCH	/writers/{id}	Update all writer' record	200 OK	400 DATA_VALIDATION_ERROR, 404 NOT_FOUND
DELETE	/writers/{id}	Delete writer by id	200 OK	400 DATA_VALIDATION_ERROR, 404 NOT_FOUND
GET	/api.raml	Raml API documentation	200 OK

Start REST API server

• Mongodb storage starting

  DB_URL=localhost:27017/database DB_AUTH=user:password node index.js

• Memory storage starting (all data will save in the memory and will be erased after restart, no horizontal scalability)

  DB_STORAGE=memory node index.js

Searching

Define field name with searching text after ? in the URL to find necessary resource. Searching text can be regular expression.

Examples

• Find male writers

  curl 127.0.0.1:8877/writers?sex=M
    [{"name":"Alexandre Dumas","sex":"M","_id":"5e806693-727b-4956-b539-e797d5bcef2b"}]

• Find writers with name begins with alex, using regular expression, case insensitive

  curl "127.0.0.1:8877/writers?name=/^alex/i"
    [{"name":"Alexandra Ripley","sex":"F","_id":"1bec2412-cdd3-4e78-b22b-25a1006e016a"},{"name":"Alexandre Dumas","sex":"M","_id":"5e806693-727b-4956-b539-e797d5bcef2b"}]

Filters and orders

All filter and orders parameters are located after ? sign in the URL.

Parameter name	Synonyms	Description
_fields	_filter	List field names to show, separate by comma
_sort	_order	List field names to sort, separate by comma, descending sort if begins with '-'
_start	_begin, _page	Start page
_limit	_per_page	Limit per page

Examples

• Find all writers, show only name field, sorting by name

  curl "127.0.0.1:8877/writers?_filter=name&_sort=name"
    [{"name":"Alexandra Ripley","sex":"F","_id":"1bec2412-cdd3-4e78-b22b-25a1006e016a"},{"name":"Alexandre Dumas","sex":"M","_id":"5e806693-727b-4956-b539-e797d5bcef2b"}]

• Find alex in writers, case insensitive, show only name field, sort by name descending

  curl "127.0.0.1:8877/writers?name=/alex/i&_filter=name&_sort=-name"
    [{"name":"Alexandre Dumas","_id":"171b51f5-1dc9-4b3c-ad1f-6af8c9a53c3a"},{"name":"Alexandra Ripley","_id":"10b7d763-4ea4-4b56-924c-2e6b4b426b31"}]

HATEOAS

Each response is complemented by _links object which refer to other methods and resources using URIs as key. For example, result of POST response:

{"name":"Alexandra Ripley","sex":"F","_id":"40abf64d-a317-4735-a8d2-a8fe08fd4a5b","_links":{"/writers/40abf64d-a317-4735-a8d2-a8fe08fd4a5b":{"self":"GET","update":"PUT","replace":"PATCH","delete":"DELETE"},"/writers/40abf64d-a317-4735-a8d2-a8fe08fd4a5b/books":{"books":"GET"}}}

This document includes links to both /writers/40abf64d-a317-4735-a8d2-a8fe08fd4a5b collection and /writers/40abf64d-a317-4735-a8d2-a8fe08fd4a5b/books resource

  {
    "_links": {
      "/writers/75fc9be7-52b7-419a-8f4c-effa8eb0bacc": {
        "GET":"self",
        "PUT":"update",
        "PATCH":"replace",
        "DELETE":"delete"
      },
      "/writers": {
        "GET":"get all writers",
        "POST":"add new resource to writers",
        "DELETE":"erase writers"
      },
      "/writers/75fc9be7-52b7-419a-8f4c-effa8eb0bacc/books": {
        "GET":"get books",
        "POST":"add books",
        "DELETE":"delete books"
      }
    }
  }

Lnked Usage Example

// index.js
var Api = require('create-rest-api');
var api = new Api();
 
api.model('writers', {
  name: { type: 'string', required: true },
  sex: { type: 'any', one: ['M', 'F'] }
});
 
api.model('books', {
  name: { type: 'string', required: true },
  year: { type: 'integer' },
  writers: { type: 'array', link: 'writers' },
});
 
api.start();

Methods

Method	URL	Description	Posible errors
GET	/writers	List of writers	404: NOT_FOUND
GET	/books	List of books	404: NOT_FOUND
GET	/writers/{id}	Single writer info	404: NOT_FOUND
GET	/books/{id}	Single book info	404: NOT_FOUND
GET	/writers/{id}/books	All writer's books	404: NOT_FOUND
GET	/books/{id}/writers	List of writers, linked to book	404: NOT_FOUND
POST	/writers	Add new writer	400: DATA_VALIDATION_ERROR
POST	/writers/{id}/books	Add new writer's books	400: DATA_VALIDATION_ERROR
POST	/books	Add new book	400: DATA_VALIDATION_ERROR
POST	/books/{id}/writers	Add writer, linked to book	400: DATA_VALIDATION_ERROR
PUT	/writers/{id}	Update some writer's information	400: DATA_VALIDATION_ERROR, 404: NOT_FOUND
PUT	/books/{id}	Update some book's information	400: DATA_VALIDATION_ERROR, 404: NOT_FOUND
PATCH	/writers/{id}	Update all writer's record	400: DATA_VALIDATION_ERROR, 404: NOT_FOUND
PATCH	/books/{id}	Update all books's record	400: DATA_VALIDATION_ERROR, 404: NOT_FOUND
DELETE	/writers/{id}	Delete writer by id	400: DATA_VALIDATION_ERROR, 404: NOT_FOUND
DELETE	/books/{id}	Delete book by id	400: DATA_VALIDATION_ERROR, 404: NOT_FOUND
GET	/api.raml	API documentation

Examples

• Add new document

  curl -X POST -H 'Content-Type: application/json' -d '{"name":"Alexandre Dumas"}' 127.0.0.1:8877/writers
  {"name":"Alexandre Dumas","_id":"5bdac691-7f6c-470f-94e7-24e7986e3dae","_links":{"self":{"href":"writers/5bdac691-7f6c-470f-94e7-24e7986e3dae"}}}

• Get all documents

  curl 127.0.0.1:8877/writers
  [{"_id":"5bdac691-7f6c-470f-94e7-24e7986e3dae","name":"Alexandre Dumas"}]

• Get one document by id

  curl 127.0.0.1:8877/writers/5bdac691-7f6c-470f-94e7-24e7986e3dae
  {"_id":"5bdac691-7f6c-470f-94e7-24e7986e3dae","name":"Alexandre Dumas"}

• Update part of document

  curl -X PATCH -H 'Content-Type: application/json' -d '{"sex":"M"}' 127.0.0.1:8877/writers/5bdac691-7f6c-470f-94e7-24e7986e3dae
  {"_id":"5bdac691-7f6c-470f-94e7-24e7986e3dae","name":"Alexandre Dumas","sex":"M"}

• Replace document

  curl -X PUT -H 'Content-Type: application/json' -d '{"name":"Alexandre Dumas"}' 127.0.0.1:8877/writers/5bdac691-7f6c-470f-94e7-24e7986e3dae
  {"_id":"5bdac691-7f6c-470f-94e7-24e7986e3dae","name":"Alexandre Dumas"}

• Delete document

  curl -X DELETE 127.0.0.1:8877/writers/5bdac691-7f6c-470f-94e7-24e7986e3dae
  {"ok":1,"_id":"5bdac691-7f6c-470f-94e7-24e7986e3dae"}

• Add two writers: Alexandra Ripley and Alexandre Dumas

  curl -X POST -H 'Content-Type: application/json' -d '{"name":"Alexandra Ripley","sex":"F"}' 127.0.0.1:8877/writers
    {"name":"Alexandra Ripley","sex":"F","_id":"1bec2412-cdd3-4e78-b22b-25a1006e016a","_links":{"self":{"href":"writers/1bec2412-cdd3-4e78-b22b-25a1006e016a"}}}
  curl -X POST -H 'Content-Type: application/json' -d '{"name":"Alexandre Dumas", "sex":"M"}' 127.0.0.1:8877/writers
  {"name":"Alexandre Dumas","sex":"M","_id":"6b9576dd-730a-41e1-97b3-41ee67cf9e4f","_links":{"self":{"href":"writers/6b9576dd-730a-41e1-97b3-41ee67cf9e4f"}}}

• Add couple books

  curl -X POST -H 'Content-Type: application/json' -d '{"name":"The Three Musketeers", "writers":["6b9576dd-730a-41e1-97b3-41ee67cf9e4f"]}' 127.0.0.1:8877/books
  {"name":"The Three Musketeers","writers":["6b9576dd-730a-41e1-97b3-41ee67cf9e4f"],"_id":"7801cc6d-84f4-4506-8eaa-56e5369983fc","_links":{"self":{"href":"books/7801cc6d-84f4-4506-8eaa-56e5369983fc"}}}

  curl -X POST -H 'Content-Type: application/json' -d '{"name":"The Count of Monte Cristo", "writers":["6b9576dd-730a-41e1-97b3-41ee67cf9e4f"]}' 127.0.0.1:8877/books
  {"name":"The Count of Monte Cristo","writers":["6b9576dd-730a-41e1-97b3-41ee67cf9e4f"],"_id":"5435b002-ef7b-4ff1-9dd1-9a0ff22c829a","_links":{"self":{"href":"books/5435b002-ef7b-4ff1-9dd1-9a0ff22c829a"}}}

• Find books by writer

  curl 127.0.0.1:8877/writers/6b9576dd-730a-41e1-97b3-41ee67cf9e4f/books
  [{"name":"The Three Musketeers","writers":["6b9576dd-730a-41e1-97b3-41ee67cf9e4f"],"_id":"7801cc6d-84f4-4506-8eaa-56e5369983fc"},{"name":"The Count of Monte Cristo","writers":["6b9576dd-730a-41e1-97b3-41ee67cf9e4f"],"_id":"5435b002-ef7b-4ff1-9dd1-9a0ff22c829a"}]

• Find writers by books

  curl 127.0.0.1:8877/books/7801cc6d-84f4-4506-8eaa-56e5369983fc/writers
  [{"name":"Alexandre Dumas","sex":"M","_id":"6b9576dd-730a-41e1-97b3-41ee67cf9e4f"}]

Error examples

  curl 127.0.0.1:8877/writers
  {"status":404,"name":"NOT_FOUND","message":"writers not found","developerMessage":{}}

  curl 127.0.0.1:8877/writers/123
  {"status":404,"name":"NOT_FOUND","message":"writer not found","developerMessage":{"_id":"123"}}

  curl -X POST -H 'Content-Type: application/json' -d '{"sex":"yes"}' 127.0.0.1:8877/writers
  {"status":400,"name":"DATA_VALIDATION_ERROR","message":"Field .sex not matched with type any. Field .name not found","developerMessage":{"text":"Field .sex not matched with type any. Field .name not found","notMatched":{".sex":"any"},"notFound":[".name"]}}

  curl 127.0.0.1:8877/writers/6b9576dd-730a-41e1-97b3-41ee67cf9e4f/books
  {"status":404,"name":"NOT_FOUND","message":"books not found","developerMessage":{"writers":{"$in":["6b9576dd-730a-41e1-97b3-41ee67cf9e4f"]}}}

  curl -X DELETE 127.0.0.1:8877/books/d3f49bee-510e-44b5-9ee6-0e7440b053bc
  {"status":404,"name":"NOT_FOUND","message":"book not found","developerMessage":{"_id":"d3f49bee-510e-44b5-9ee6-0e7440b053bc"}}

Change Log

all changes

Created by

Dimitry Ivanov [e-mail] # curl -A cv ivanoff.org.ua