Requests and Responses

End-points:

The paths of REST end-points:

The end-point path consists of three parts: /[api-mount-path/]model-exposition-path/[additional-path/]

  • api-mount-path -- the path that assigned in the use method called to bind the ModelAPIExpress to your main application. This path could be omitted in two cases: 1) the path omitted in the use method, or 2) the ModelAPIExpress is main application (it's also possible)
  • model-exposition-path - by default it is the collection name of exposed Model. This path could be overrided by assigning path api-option on the Model-routes level (see API-configuration)
  • additional-path - by default it is omitted. It could be assigned by specifying path api-option on the end-point level (see API-configuration)

merest grants that assigned by default paths for different end-points are not intercepted, but it doesn't control the interception for custom assigned paths.

Common responses

404 - Document was not found (or doesn't exist)

merest returns this response if it couldn't find the Document (including just created) by id in the url and/or doesn't match the assigned filter api-option

Status: 404
Content-Type: application/json; charset=utf-8

{"error": true, "code": 404, "message": "..."}
405 - End-point is not supported:

merest returns this response if requested path doesn't associated with any handler.

Note: instead of common practice for HTTP merest return 405 HTTP Response code, but not 404 that means: Document was not found (or doesn't exist).

Status: 405
Content-Type: application/json; charset=utf-8

{"error": true, "code": 405, "message": "Not Supported"}
422 - Validation error
Status: 422
Content-Type: application/json; charset=utf-8

{
  "error": true,
  "code": 422,
  "message": "..."
  [,"errors": {
    ...
  }]
  [,"stack": [
    ...
  ]]
}

The fields errors and stack are optional.

End-point options:

Returns list of available end-points with short description.

Request:

OPTIONS /end-point-path/ HTTP/1.1
HOST: hostname:port

If you client doesn't support OPTIONS HTTP-method directly, use this message:

POST /end-point-path/ HTTP/1.1
HOST: hostname:port
X-HTTP-Method-Override: OPTIONS

Responses:

Success:

Status: 200
Content-Type: application/json; charset=utf-8

[
  ["method", "path", "descriptions"],
  ["method", "path", "descriptions"],
  ...
  ["method", "path", "descriptions"]
]

Other responses:

  • 405 - End-point is not supported

End-point search:

Returns the list of Documents that satisfy query passed to call.

Request for end-point mounted on GET:

GET /end-point-path/[?field1=value1&field2=value2&_sort=fieldName&_limit=number&_skip=number] HTTP/1.1
HOST: hostname:port

Query String could contain pares field=value separated by the &. Since the merest v. 1.2.0 the extended search opportunties is avaliable:

  • field__ne=value - the field is not equal to the value
  • field__in=value,value,value - the field is one of the list of values (separated by coma)
  • field__nin=value,value,value - the field is not in the list of values (separated by coma)
  • field__gt=value - the field is greater then the value
  • field__gte=value - the field is greater then or equal to the value
  • field__lt=value - the field is less then the value
  • field__lte=value - the field is less then or equal to the value
  • field__re=reg-exp - the field matches the pattern
  • field__ex=flag - the field exists (if flag is 1, true etc.) or doesn't exists (if flag is 0 or false)

Also query string could contain three additional parameters:

  • _sort=fieldName
  • _limit=maximum number of documents in Response
  • _skip=number of document that should be skipped in Response

These parameters (all of them or any of them) will be ignored if appropriate API-configuration option will be assigned to false

To use all MongoDB query opportunities you could mount the create end-point on the POST HTTP-method and specify additional-path.

In security reasons I don't recommend to do so. The better way is to extend Model with static methods that accepts only necessary parameters and builds safe query. However merest allows you to mount search end-point on POST method and form query on the client-side.

Request for end-point mounted on POST:

POST /end-point-path/[?_sort=fieldName&_limit=number&_skip=number] HTTP/1.1
HOST: hostname:port
Content-Type: application/json

<Mongoose Query-Object>

Success:

Status: 200
Content-Type: application/json; charset=utf-8

[
  { ... },
  { ... }
  ...
  { ... }
]

If no one Document found, the merest returns empty Array

Other responses:

  • 405 - End-point is not supported

End-point create:

Creates new Document, finds it and returns to the client.

Request:

POST /end-point-path/ HTTP/1.1
HOST: hostname:port
Content-Type: application/json

<Mongoose Model Object>

Responses:

Success:

Status: 200
Content-Type: application/json; charset=utf-8

{ ... }

406 - Method doesn't allow to update object

Status: 406
Content-Type: application/json; charset=utf-8

{
  "error": true,
  "code": 406,
  "message": "This method doesn't allow to update a(n) ${Model.name}"
}

Other responses:

  • 404 - Document was not found (or doesn't exist)
  • 405 - End-point is not supported
  • 422 - Validation error

The Response with status code 404 could be returned if created object doesn't match filter api-option specified on the exposition.

End-point details:

Returns Document of the exposed Model by its id specified in the URL.

Request:

GET /end-point-path/:id HTTP/1.1
HOST: hostname:port

Responses:

Success:

Status: 200
Content-Type: application/json; charset=utf-8

{ ... }

Other responses:

  • 404 - Document was not found (or doesn't exist)
  • 405 - End-point is not supported

End-point update:

Updates the existing Document, returns it to the client.

Request:

POST /end-point-path/:id HTTP/1.1
HOST: hostname:port
Content-Type: application/json

<Mongoose $set-object>

Responses:

Success:

Status: 200
Content-Type: application/json; charset=utf-8

{ ... }

Other responses:

  • 404 - Document was not found (or doesn't exist)
  • 405 - End-point is not supported
  • 422 - Validation error

End-point delete:

Finds Document by id specified in the URL, deletes it and returns empty JSON-object to the client.

Request:

DELETE /end-point-path/:id HTTP/1.1
HOST: hostname:port

If you client doesn't support DELETE HTTP-method directly, use this message:

POST /end-point-path/ HTTP/1.1
HOST: hostname:port
X-HTTP-Method-Override: DELETE

Responses:

Success:

Status: 200
Content-Type: application/json; charset=utf-8

{}

Other responses:

  • 404 - Document was not found (or doesn't exist)
  • 405 - End-point is not supported

Response customization

Merest allows to customize all responses. In order to do that you should define function that transforms prepared response and specify this function in api configuration

Example:

// api.js
var api = new merest.ModelAPIExpress({
  transformResponse: prepareResponse
});

...

function prepareResponse(req, res) {
  var body = {
    status: this.status,
    data: this.body
  };
  this.status = 200;
  this.body = body;
}

You could access the following fields inside a transforming function:

  • this.status -- the HTTP Status
  • this.body -- the response body
  • this.apiMethod -- the API end-point name (create, search, details etc.)
  • this.apiInstanceMethod -- the name of exposed instance method
  • this.apiStaticMethod -- the name of exposed static method
  • this.api -- the API-object (the child of express);
  • this.modelAPI -- the router dispatches end-points related the model
  • this.model -- the model name

You should reassign this.status and this.body to override default HTTP-response. The function returns nothing.

Calling API:

curl -X OPTIONS http://localhost:1337/api/v1/

Output:

{
  "status": 200,
  "data": [
    ["options", "/api/v1/", "List all end-points of current application"],
    ["options", "/api/v1/vectors/", "List API-options for vectors"],
    ["get", "/api/v1/vectors/", "List/Search all vectors"],
    ["post", "/api/v1/vectors/", "Create a new Vector"],
    ["get", "/api/v1/vectors/:id", "Find a Vector by Id"],
    ["post", "/api/v1/vectors/:id", "Find a Vector by Id and update it (particulary)"],
    ["delete", "/api/v1/vectors/:id", "Find a Vector by Id and delete it."]
  ]
}

Also you can run this example:

git clone https://github.com/DScheglov/merest.git
cd merest
npm install
node examples/transform-response/server.js

Next (Installation) >