REST Client

Connect to your Feathers API using REST/HTTP with fetch, axios, or superagent

The REST client allows you to connect to a Feathers API using HTTP/HTTPS. It supports three different HTTP libraries: fetch (recommended), axios, and superagent.

Installation

Full Client

npm install @feathersjs/client

REST Only

npm install @feathersjs/rest-client

For Node.js, also install your preferred HTTP library:

# Using fetch (recommended)
npm install node-fetch

# Or using axios
npm install axios

# Or using superagent
npm install superagent

Browser Usage

In the browser, use the native fetch API:

1. Include the library

   <script src="//unpkg.com/@feathersjs/client@^5.0.0/dist/feathers.js"></script>
   
2. Create the application

   const app = feathers()
   
3. Configure REST client

   const restClient = feathers.rest('http://localhost:3030')
   app.configure(restClient.fetch(window.fetch.bind(window)))
   
4. Use services

   const todos = app.service('todos')
   
   // Create a todo
   const todo = await todos.create({
     text: 'Learn Feathers',
     complete: false
   })
   
   // Find all todos
   const allTodos = await todos.find()
   

Node.js Usage

Fetch (Recommended)

Using the modern fetch API with node-fetch:

import feathers from '@feathersjs/client'
import rest from '@feathersjs/rest-client'
import fetch from 'node-fetch'

const app = feathers()

// Configure REST client with fetch
const restClient = rest('http://localhost:3030')
app.configure(restClient.fetch(fetch))

// Use services
const todos = app.service('todos')
const results = await todos.find()

Axios

Using axios for HTTP requests:

import feathers from '@feathersjs/client'
import rest from '@feathersjs/rest-client'
import axios from 'axios'

const app = feathers()

// Configure REST client with axios
const restClient = rest('http://localhost:3030')
app.configure(restClient.axios(axios))

// Use services
const todos = app.service('todos')
const results = await todos.find()

Superagent

Using superagent for HTTP requests:

import feathers from '@feathersjs/client'
import rest from '@feathersjs/rest-client'
import superagent from 'superagent'

const app = feathers()

// Configure REST client with superagent
const restClient = rest('http://localhost:3030')
app.configure(restClient.superagent(superagent))

// Use services
const todos = app.service('todos')
const results = await todos.find()

Service Methods

All standard Feathers service methods are available:

const todos = app.service('todos')

// Find - GET /todos
const results = await todos.find({
  query: {
    complete: false,
    $limit: 10
  }
})

// Get - GET /todos/:id
const todo = await todos.get(1)

// Create - POST /todos
const created = await todos.create({
  text: 'Learn Feathers',
  complete: false
})

// Update - PUT /todos/:id
const updated = await todos.update(1, {
  text: 'Learn Feathers (updated)',
  complete: true
})

// Patch - PATCH /todos/:id
const patched = await todos.patch(1, {
  complete: true
})

// Remove - DELETE /todos/:id
const removed = await todos.remove(1)

Custom Headers

You can pass custom headers with any service call:

const todos = app.service('todos')

// Single request with custom headers
const results = await todos.find({
  headers: {
    'Authorization': 'Bearer your-token',
    'X-Custom-Header': 'custom-value'
  }
})

// Works with all methods
const created = await todos.create(
  { text: 'New todo' },
  {
    headers: {
      'Authorization': 'Bearer your-token'
    }
  }
)

Connection Options

You can pass connection-specific options using params.connection:

Fetch

const todos = app.service('todos')

const results = await todos.find({
  connection: {
    headers: {
      'Authorization': 'Bearer token'
    },
    credentials: 'include', // Send cookies
    mode: 'cors'
  }
})

Axios

const todos = app.service('todos')

const results = await todos.find({
  connection: {
    timeout: 5000,
    withCredentials: true,
    responseType: 'json'
  }
})

Superagent

const todos = app.service('todos')

const results = await todos.find({
  connection: {
    'Authorization': 'Bearer token',
    'Accept': 'application/json'
  }
})

Custom Methods

REST client supports custom service methods:

import feathers from '@feathersjs/client'
import rest from '@feathersjs/rest-client'
import fetch from 'node-fetch'

const app = feathers()
const restClient = rest('http://localhost:3030')
app.configure(restClient.fetch(fetch))

// Register service with custom methods
app.use('todos', restClient.service('todos'), {
  methods: ['find', 'get', 'create', 'patch', 'customMethod']
})

const todos = app.service('todos')

// Call custom method - POST /todos with X-Service-Method header
const result = await todos.customMethod({ data: 'value' })

Custom methods are sent as POST requests with a special X-Service-Method header indicating the method name.

Direct Service Usage

You can create service instances without configuring the app:

import rest from '@feathersjs/rest-client'
import fetch from 'node-fetch'

const connection = rest('http://localhost:3030').fetch(fetch)
const todosService = connection.service('todos')

// Use the service directly
const todos = await todosService.find()
const todo = await todosService.get(1)

Error Handling

REST errors are automatically converted to Feathers errors:

import { errors } from '@feathersjs/client'

try {
  const todo = await todos.get(999)
} catch (error) {
  console.log(error.code) // 404
  console.log(error.message) // 'Not Found'
  console.log(error.className) // 'not-found'
  console.log(error.data) // Additional error data
  console.log(error.response) // Original HTTP response

  // Check error type
  if (error instanceof errors.NotFound) {
    console.log('Todo not found')
  }
}

Base URL and Service Paths

The REST client constructs URLs based on the base URL and service name:

// Base URL: http://localhost:3030
const restClient = rest('http://localhost:3030')

// Service 'todos' -> http://localhost:3030/todos
const todos = app.service('todos')

// Service 'api/v1/users' -> http://localhost:3030/api/v1/users
const users = app.service('api/v1/users')

TypeScript Support

The REST client has full TypeScript support:

import { feathers } from '@feathersjs/client'
import rest from '@feathersjs/rest-client'
import fetch from 'node-fetch'
import type { RestService } from '@feathersjs/rest-client'

interface Todo {
  id: number
  text: string
  complete: boolean
}

interface ServiceTypes {
  todos: RestService<Todo>
}

const app = feathers<ServiceTypes>()
const restClient = rest<ServiceTypes>('http://localhost:3030')
app.configure(restClient.fetch(fetch))

const todos = app.service('todos')
const todo: Todo = await todos.get(1)

Configuration Options

You can pass options when creating the REST client:

const restClient = rest('http://localhost:3030')

// Configure with default headers
const connection = restClient.fetch(fetch, {
  headers: {
    'X-Api-Version': '1.0',
    'Accept': 'application/json'
  }
})

app.configure(connection)

Next Steps

Socket.io Client

Learn about real-time connections with WebSocket support

Authentication

Add authentication to your client application