Vanilla REST

Once set up on the server, there are several ways to connect to the REST API of a Feathers service. Keep in mind that while clients connected via websockets will receive real-time events from other REST API calls, you can't get real-time updates over the HTTP API without resorting to polling.

You can communicate with a Feathers server using any HTTP REST client. The following section describes what HTTP method, body and query parameters belong to which service method call.

All query parameters in a URL will be set as params.query on the server. Other service parameters can be set through hooks and Express middleware. URL query parameter values will always be strings. Conversion (e.g. the string 'true' to boolean true) can be done in a hook as well.

The body type for POST, PUT and PATCH requests is determined by the Express body-parser middleware which has to be registered before any service. You should also make sure you are setting your Accepts header to application/json.

find

Retrieves a list of all matching resources from the service

GET /messages?status=read&user=10

Will call messages.find({ query: { status: 'read', user: '10' } }) on the server.

If you want to use any of the built-in find operands ($le, $lt, $ne, $eq, $in, etc.) the general format is as follows:

GET /messages?field[$operand]=value&field[$operand]=value2

For example, to find the records where field status is not equal to active you could do

GET /messages?status[$ne]=active

To get really complex queries using the URL syntax, the back-end must implement the extended query string qs() (query string parser) middleware layer. This is accomplished within the code by adding a

app.set('query parser', 'extended');

line before any routes are introduced.

Once that is in place the sky is basically the limit as far as how complex your queries can go. Basically you want to create URL queries that will match the same structure as the object query style syntax. Please refer to the qs documentation at extended query string for more information. Here is a simple example of how one can use the $in operand from a URL:

GET /messages?name[$in]=John&name[$in]=Jane&name[$in]=Joe

Gets translated into the query:

{ query: {
    name: {
      $in: ['John', 'Jane', 'Joe']
    }
  }
}

N.B. You may also want to check the documentation of the underlying datastore adaptor that maybe in use, as sometimes they extend the basic operands available to include ones unique to that datastore. The documentation will probably be in terms of how to use it within a feathers query object, but with your new found qs() powers you should be able to translate that now into an appropriate URL sequence.

get

Retrieve a single resource from the service.

GET /messages/1

Will call messages.get(1, {}) on the server.

GET /messages/1?fetch=all

Will call messages.get(1, { query: { fetch: 'all' } }) on the server.

create

Create a new resource with data which may also be an array.

POST /messages
{ "text": "I really have to iron" }

Will call messages.create({ "text": "I really have to iron" }, {}) on the server.

POST /messages
[
  { "text": "I really have to iron" },
  { "text": "Do laundry" }
]

update

Completely replace a single or multiple resources.

PUT /messages/2
{ "text": "I really have to do laundry" }

Will call messages.update(2, { "text": "I really have to do laundry" }, {}) on the server. When no id is given by sending the request directly to the endpoint something like:

PUT /messages?complete=false
{ "complete": true }

Will call messages.update(null, { "complete": true }, { query: { complete: 'false' } }) on the server.

ProTip: update is normally expected to replace an entire resource which is why the database adapters only support patch for multiple records.

patch

Merge the existing data of a single or multiple resources with the new data.

PATCH /messages/2
{ "read": true }

Will call messages.patch(2, { "read": true }, {}) on the server. When no id is given by sending the request directly to the endpoint something like:

PATCH /messages?complete=false
{ "complete": true }

Will call messages.patch(null, { complete: true }, { query: { complete: 'false' } }) on the server to change the status for all read messages.

This is supported out of the box by the Feathers database adapters

remove

Remove a single or multiple resources:

DELETE /messages/2?cascade=true

Will call messages.remove(2, { query: { cascade: 'true' } }). When no id is given by sending the request directly to the endpoint something like:

DELETE /messages?read=true

Will call messages.remove(null, { query: { read: 'true' } }) to delete all read messages.

REST