REST Client

The @feathersjs/rest-client module provides REST API connectivity for Feathers client applications. It supports multiple HTTP libraries including Fetch, Axios, and Superagent.

Installation

npm install @feathersjs/rest-client

You’ll also need one of the supported HTTP libraries:

# For Fetch API (browser or node-fetch)
npm install node-fetch

# For Axios
npm install axios

# For Superagent  
npm install superagent

restClient()

Creates a REST client connection factory.

Signature

function restClient<ServiceTypes = any>(base?: string): Transport<ServiceTypes>

base

string

default:"''"

Base URL for all service requests

Returns

Transport

Transport<ServiceTypes>

An object with connection handlers for different HTTP libraries:

fetch: Fetch API connection
axios: Axios connection
superagent: Superagent connection

fetch()

Configures REST client to use the Fetch API.

Signature

rest(base).fetch(
  connection: typeof fetch,
  options?: any,
  Service?: typeof Base
): TransportConnection<ServiceTypes>

connection

typeof fetch

required

Fetch function (browser fetch or node-fetch)

options

object

Default fetch options applied to all requests

Service

typeof Base

Custom service class extending Base

Example

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

// Browser
const app = feathers()
app.configure(rest('http://api.example.com').fetch(window.fetch))

// Node.js
import fetch from 'node-fetch'
const app = feathers()
app.configure(rest('http://api.example.com').fetch(fetch))

// With options
app.configure(rest('http://api.example.com').fetch(fetch, {
  headers: {
    'Accept': 'application/json'
  }
}))

axios()

Configures REST client to use Axios.

Signature

rest(base).axios(
  connection: AxiosInstance,
  options?: any,
  Service?: typeof Base
): TransportConnection<ServiceTypes>

connection

AxiosInstance

required

Axios instance

options

object

Default axios options applied to all requests

Service

typeof Base

Custom service class extending Base

Example

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

const app = feathers()

// Basic setup
app.configure(rest('http://api.example.com').axios(axios))

// With custom axios instance
const axiosInstance = axios.create({
  timeout: 10000,
  headers: {
    'X-Custom-Header': 'value'
  }
})

app.configure(rest('http://api.example.com').axios(axiosInstance))

superagent()

Configures REST client to use Superagent.

Signature

rest(base).superagent(
  connection: SuperAgentStatic,
  options?: any,
  Service?: typeof Base
): TransportConnection<ServiceTypes>

connection

SuperAgentStatic

required

Superagent library

options

object

Default superagent options applied to all requests

Service

typeof Base

Custom service class extending Base

Example

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

const app = feathers()

app.configure(rest('http://api.example.com').superagent(superagent))

// With options
app.configure(rest('http://api.example.com').superagent(superagent, {
  headers: {
    'Authorization': 'Bearer token'
  }
}))

Service Methods

REST client services implement all standard Feathers service methods:

find()

const messages = app.service('messages')
const result = await messages.find({
  query: {
    $limit: 10,
    read: false
  }
})

get()

const message = await messages.get(123, {
  query: { $select: ['text', 'userId'] }
})

create()

const newMessage = await messages.create({
  text: 'Hello world!',
  userId: 1
})

update()

const updated = await messages.update(123, {
  text: 'Updated text',
  userId: 1
})

patch()

const patched = await messages.patch(123, {
  read: true
})

remove()

const removed = await messages.remove(123)

Custom Methods

app.use('/messages', messageService, {
  methods: ['find', 'get', 'create', 'archive']
})

const messages = app.service('messages')
await messages.archive({ messageId: 123 })

Params

REST client params support:

query

object

Query parameters sent as URL query string

headers

object

Custom HTTP headers for the request

route

object

Route parameters for parameterized URLs

connection

object

HTTP library-specific options for this request

Example

const messages = app.service('messages')

await messages.get(123, {
  query: { $select: ['text'] },
  headers: {
    'Authorization': 'Bearer token123'
  },
  connection: {
    // Fetch-specific options
    credentials: 'include'
  }
})

Error Handling

REST client automatically converts HTTP errors to Feathers errors:

try {
  await messages.get(999)
} catch (error) {
  console.log(error.name)     // 'NotFound'
  console.log(error.code)     // 404
  console.log(error.message)  // 'Not Found'
  console.log(error.data)     // Additional error data
}

Error classes include:

BadRequest (400)
NotAuthenticated (401)
PaymentError (402)
Forbidden (403)
NotFound (404)
MethodNotAllowed (405)
Timeout (408)
Conflict (409)
Unprocessable (422)
GeneralError (500)
Unavailable (503)

HTTP Method Mapping

REST client maps service methods to HTTP methods:

Service Method	HTTP Method	URL Pattern
`find()`	GET	`/messages`
`get(id)`	GET	`/messages/:id`
`create(data)`	POST	`/messages`
`update(id, data)`	PUT	`/messages/:id`
`patch(id, data)`	PATCH	`/messages/:id`
`remove(id)`	DELETE	`/messages/:id`

Custom methods use POST with X-Service-Method header:

// Custom method
await messages.archive({ id: 123 })

// Sends:
// POST /messages
// Headers: { X-Service-Method: 'archive' }
// Body: { id: 123 }

Authentication

Integrate with Feathers authentication:

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

const app = feathers()

app.configure(rest('http://api.example.com').axios(axios))
app.configure(auth())

// Authenticate
await app.authenticate({
  strategy: 'local',
  email: 'user@example.com',
  password: 'password'
})

// Authentication token automatically included in subsequent requests
const messages = await app.service('messages').find()

Complete Example

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

// Create client app
const app = feathers()

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

// Configure authentication
app.configure(auth({
  storageKey: 'feathers-jwt'
}))

// Use services
const messages = app.service('messages')

// Authenticate
try {
  await app.authenticate({
    strategy: 'local',
    email: 'user@example.com',
    password: 'password'
  })
  
  // Create a message
  const message = await messages.create({
    text: 'Hello from REST client!'
  })
  
  console.log('Created:', message)
  
  // Find all messages
  const allMessages = await messages.find({
    query: { $limit: 10 }
  })
  
  console.log('Found:', allMessages.data)
} catch (error) {
  console.error('Error:', error)
}

Core

Authentication

Databases

Transports

Schema

Utilities

REST Client

REST Client

Installation

restClient()

Signature

Returns

fetch()

Signature

Example

axios()

Signature

Example

superagent()

Signature

Example

Service Methods

find()

get()

create()

update()

patch()

remove()

Custom Methods

Params

Example

Error Handling

HTTP Method Mapping

Authentication

Complete Example

Core

Authentication

Databases

Transports

Schema

Utilities

​REST Client

​Installation

​restClient()

​Signature

​Returns

​fetch()

​Signature

​Example

​axios()

​Signature

​Example

​superagent()

​Signature

​Example

​Service Methods

​find()

​get()

​create()

​update()

​patch()

​remove()

​Custom Methods

​Params

​Example

​Error Handling

​HTTP Method Mapping

​Authentication

​Complete Example

REST Client

Installation

restClient()

Signature

Returns

fetch()

Signature

Example

axios()

Signature

Example

superagent()

Signature

Example

Service Methods

find()

get()

create()

update()

patch()

remove()

Custom Methods

Params

Example

Error Handling

HTTP Method Mapping

Authentication

Complete Example