Skip to main content

​
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

Register custom service 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 MethodHTTP MethodURL 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: '[email protected]',
  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: '[email protected]',
    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)
}

Build docs developers (and LLMs) love

Get started for freeTalk to us