restii
v0.4.0
Published
Energize your REST API with React hooks and a centralized cache.
Downloads
18
Maintainers
Readme
restii
Energize your REST API 🌿 with React hooks and a centralized cache.
Features:
- 🚀 A set of React hooks for querying HTTP API data
- 💾 Turnkey API response caching
- 🖇 Parallel request de-duplication
- 📡 Support for API requests and cache queries outside of React components (in sagas, thunks, etc.)
- 📥 Parses response bodies of any data type (
'json'
,'blob'
,'text'
) - 💡 Designed with full Typescript support
Contents
- Motivation
- Basic Usage
- Installation & Setup
- Guide (wip)
- Comparison to similar libraries (wip)
- Usage with Redux (wip)
- API (wip)
Motivation
At d1g1t, we make over 400 REST API calls in our enterprise investment advisor platform. Over time, as we started using React hooks and wanted to introduce caching optimizations, it was clear that we needed to overhaul our internal REST API fetching library to use patterns that scale with our app.
restii
synthesizes patterns from other libraries, such as apollo-client
, swp
, and react-query
. The primary difference is that it's specifically designed for making HTTP calls to your API. It allows you to request API data with URL paths, query parameters, request bodies, and HTTP headers. The caching layer will deterministically map these HTTP request parameters to response bodies, allowing the user to easily query their API and defer caching logic to restii
.
Since it works well for d1g1t's purposes, we decided to open-source the library to help others who are building a REST API-consuming React application.
Basic Usage
Query your API (ex. fetching a user's profile):
import React from 'react'
import {useApiQuery} from 'restii'
const MyComponent = (props) => {
const [userQuery] = useApiQuery({url: `/users/${props.userId}`})
if (userQuery.error) {
// display error
}
if (userQuery.loading) {
// display loading state
}
return <h1>{userQuery.data.firstName}</h1>
}
As you start adding more API requests, we strongly recommend organizing your request definitions into centralized "endpoint" classes, grouped by domain/resource.
Continuing our example, we'll create a UserEndpoints
class to define endpoints under the '/users'
base path. We'll subclass restii#HttpEndpoints
, which gives us static HTTP helper methods:
import {HttpEndpoints} from 'restii'
export class UserEndpoints extends HttpEndpoints {
static basePath = '/users'
static list(query) {
return super._get('', {query})
// {method: 'GET', url: '/users?serializedQuery'}
}
static create(body) {
return super._post('', {body})
// {method: 'POST', url: '/users'}
}
static findById(id) {
return super._get(`/${id}`)
// {method: 'GET', url: `/users/${id}`}
}
static update(id, body) {
return super._put(`/${id}`, {body})
// {method: 'PUT', url: `/users/${id}`, body}
}
static partialUpdate(id, body) {
return super._patch(`/${id}`, {body})
// {method: 'PATCH', url: `/users/${id}`, body}
}
static destroy(id) {
return super._delete(`/${id}`)
// {method: 'DELETE', url: `/users/${id}`}
}
// ad-hoc, custom request:
static requestPasswordReset(id, resetToken, body) {
return super._post(`/users/${id}`, {
body,
headers: {'x-reset-token': resetToken}
})
// {method: 'POST', url: `/users/${id}`, headers: {'x-reset-token': resetToken}, body}
}
}
If your endpoints follow common REST-ful conventions, you can subclass restii#RestEndpoints
(which subclasses restii#HttpEndpoints
) to reduce REST boilerplate:
import {RestEndpoints} from 'restii'
export class UserEndpoints extends RestEndpoints {
static basePath = '/users'
static list(query) {
return super._list(query)
}
static create(body) {
return super._create(body)
}
static findById(id) {
return super._findById(id)
}
static update(id, body) {
return super._update(id, body)
}
static partialUpdate(id, body) {
return super._partialUpdate(id, body)
}
static destroy(id) {
return super._destroy(id)
}
static requestPasswordReset(id, resetToken, body) {
return super._post(`/users/${id}`, {
body,
headers: {'x-reset-token': resetToken}
})
}
}
Then you can use these endpoints to make queries:
import React from 'react'
import {useApiQuery} from 'restii'
import {UserEndpoints} from 'my-app/endpoints'
const MyComponent = (props) => {
const [usersQuery] = useApiQuery(UserEndpoints.list({limit: 10}))
const [userQuery] = useApiQuery(UserEndpoints.findById(props.userId))
// ... etc
}
To make one-off requests (ie. form submissions, deletions, etc), you can use the Api
client instance directly:
import React, {useState} from 'react'
import {useApi} from 'restii'
import {UserEndpoints} from 'my-app/endpoints'
const DeleteUser = (props) => {
const api = useApi()
const [deleting, setDeleting] = useState(false)
const handleDelete = async () => {
setDeleting(true)
try {
await api.request(UserEndpoints.destroy(props.userId))
// navigate to a different page, etc.
} catch (error) {
// handle error
} finally {
setDeleting(false)
}
}
return (
<>
<button type='button' onClick={handleDeleteUser} disabled={deleting}>
Delete User
</button>
</>
)
}
Installation & Setup
Install the package as a dependency:
npm install --save restii
# or
yarn add restii
Create an Api
instance and provide it to your app:
import {Api, ApiProvider} from 'restii'
const api = new Api({
// ↓ prefixes all request urls
baseUrl: 'http://your-api.com'
})
const App = () => (
<ApiProvider api={api}>{/* render your app here */}</ApiProvider>
)
You can now start defining endpoints and making requests in your app.
Guide
Caching
How cache data is keyed
TODO explain how requests are deterministically keyed for caching (without request body)
Using the cache when requesting data
TODO explain how to use fetchPolicy
Writing to the cache directly
TODO
Dependent queries
TODO
Re-fetching a query
TODO
Custom response body parsing
TODO
Custom query string serialization
TODO
Setting default headers (ie. an auth token) for all requests
TODO
Typescript
TODO
Comparison to similar libraries
TODO: add comparisons to react-query
/swr
, rest-hooks
, apollo-graphql
(with apollo-link-rest
)
Usage with Redux
TODO
API
TODO