Feathers Client + 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.

Using the Feathers client, the feathers-rest/client module allows you to connect to a Feathers service via a REST API using jQuery, request, Superagent, Axios or Fetch as the client library.

ProTip: REST client services do emit created, updated, patched and removed events but only locally for their own instance. Real-time events from other clients can only be received by using a websocket connection.

ProTip: The base URL is relative from where services are registered. That means that a service at http://api.feathersjs.com/api/v1/messages with a base URL of http://api.feathersjs.com would be available as app.service('api/v1/messages'). With a base URL of http://api.feathersjs.com/api/v1 it would be app.service('messages').

Notice how the REST client wrapper is always initialized using a base URL:

app.configure(rest('http://api.feathersjs.com').superagent(superagent [, options]));

Default headers can be set for all libaries (except request which has its own defaults mechanism) in the options like this:

app.configure(rest('http://api.feathersjs.com').superagent(superagent, {
  headers: { 'X-Requested-With': 'FeathersJS' }
}));

jQuery

jQuery $.ajax requires an instance of jQuery passed to feathers.jquery. In most cases the global jQuery:

const feathers = require('feathers/client');
const rest = require('feathers-rest/client');
const host = 'http://api.feathersjs.com';
const app = feathers()
  .configure(rest(host).jquery(window.jQuery));

Request

The request object needs to be passed explicitly to feathers.request. Using request.defaults - which creates a new request object - is a great way to set things like default headers or authentication information:

const feathers = require('feathers/client');
const rest = require('feathers-rest/client');
const request = require('request');
const host = 'http://api.feathersjs.com';
const client = request.defaults({
  'auth': {
    'user': 'username',
    'pass': 'password',
    'sendImmediately': false
  }
});

const app = feathers()
  .configure(rest(host).request(client));

Superagent

Superagent currently works with a default configuration:

const feathers = require('feathers/client');
const rest = require('feathers-rest/client');
const superagent = require('superagent');
const host = 'http://api.feathersjs.com';
const app = feathers()
  .configure(rest(host).superagent(superagent));

Axios

Axios currently works with a default configuration:

const feathers = require('feathers/client');
const rest = require('feathers-rest/client');
const axios = require('axios');
const host = 'http://api.feathersjs.com';
const app = feathers()
  .configure(rest(host).axios(axios));

Fetch

Fetch also uses a default configuration:

const feathers = require('feathers/client');
const rest = require('feathers-rest/client');
const host = 'http://api.feathersjs.com';
const fetch = require('node-fetch');
const app = feathers()
  .configure(rest(host).fetch(fetch));

Browser Usage

Using the Feathers client, the feathers-rest/client module can be configured to used for any Ajax requests:

<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/superagent/1.2.0/superagent.min.js"></script>
<script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/core-js/2.1.4/core.min.js"></script>
<script type="text/javascript" src="//unpkg.com/feathers-client@^1.0.0/dist/feathers.js"></script>
<script type="text/javascript">
  const rest = feathers.rest('http://api.feathersjs.com');
  const app = feathers()
    .configure(feathers.hooks())
    .configure(rest.superagent(superagent));

  var messageService = app.service('messages');

  messageService.create({ text: 'Oh hai!'}).then(result => {
    console.log(result);
  }).catch(error => {
    console.error(error);
  });
</script>

Node.js Usage

Here's how to use the Feathers REST client in Node.js.

$ npm install feathers feathers-rest feathers-hooks superagent

const feathers = require('feathers');
const superagent = require('superagent');
const hooks = require('feathers-hooks')
const client = require('feathers-rest/client');
const rest = client('http://my-feathers-server.com');

const app = feathers()
  .configure(hooks())
  .configure(rest.superagent(superagent));

// This will now connect to the http://my-feathers-server.com/messages API
const messageService = app.service('messages');

messageService.create({ text: 'Oh hai!'}).then(result => {
  console.log(result);
}).catch(error => {
  console.error(error);
});

React Native Usage

Here's how you can use Feathers client with the Fetch provider in React Native.

$ npm install feathers feathers-rest feathers-hooks

import React from 'react-native';
import hooks from 'feathers-hooks';
import feathers from 'feathers/client';
import rest from 'feathers-rest/client';

const app = feathers()
  .configure(feathers.hooks())
  .configure(rest('http://my-feathers-server.com').fetch(fetch));

// Get the message service that uses a REST connection
const messageService = app.service('messages');

messageService.create({ text: 'Oh hai!'})
  .then(result => console.log(result))
  .catch(error => console.error(error));

REST