API Hooks

A front-end library for converting a REST API client into a library of useful React hooks for fetching, caching and displaying external data. The library is written in TypeScript and compiled to a JavaScript node module and accompanying typings.

Prerequisite Libraries

React (17+)

Contents

• Setting Up Your API Client
• Adding API Hooks to your project
• The Hooks
  • useQuery (GET)
  • useMutation (POST/PUT/PATCH/DELETE)
  • useRequest
  • useTools
• Configuring API Hooks
  • Application Level Settings
  • Endpoint Level Settings
  • Hook Level Settings
• Caching
  • Cache Keys
  • Refetch Queries
  • Cache Config
  • Cache Quirks
• Testing with Mock Endpoints
  • Test Keys
• Advanced Features
  • The Processing Hook
  • The Pre-processing Hook
  • Lifecycle Listeners
  • Global Listeners
  • Responders
  • Default Data
  • Payload Modifiers
  • Bookmark Parameters
• Debugging

Setting Up Your API Client

The API Hooks create method needs to be passed an API Client object. This object essentially needs to be a structured library of methods that return promises, but how you fetch your data within those methods is up to you.

For your API Client to work with this library, it must adhere to the following controller based structure:

class FirstController {
  getEndpoint = (args: { arg1?: string; arg2?: number }): Promise<string> => {
    // replace with data fetcher
    return Promise.resolve("hello world get")
  }
  postEndpoint = (args: { body?: string; }): Promise<string> => {
    // replace with data fetcher
    return Promise.resolve("hello world post")
  }
  // add additional endpoints to controller here
}

class ApiClient {
  firstController = new FirstController()
  // add additional controllers here
}

export const apiClient = new ApiClient()

NOTE: It's essential that each endpoint receives a single parameter which must be an object of key/value parameters. This is required for semantic reasons. It allows the API client author to name the parameters sent to an endpoint, this makes the commands sent to API Hooks much easier to read.

Adding API Hooks to your project

First of all, you'll need to import the API Hooks provider component and wrap the area of the DOM in which you'll be using API Hooks (usually the entire application.) NOTE: The provider component must only be used once in your app:

import * as ReactDOM from "react-dom"
import { ApiHooksStore } from "@rocketmakers/api-hooks"
import { AppComponent } from "*Root app component location*"

ReactDOM.render(
  <ApiHooksStore.Provider>
    <AppComponent />
  </ApiHooksStore.Provider>,
  document.getElementById("host"))
)

Getting the core hook library up and running is as simple as calling the create method and passing an API Client object (described above):

import { ApiHooks, EndpointIDs } from "@rocketmakers/api-hooks"
import { apiClient } from "path/to/my/apiclient"

export const apiHooks = ApiHooks.create(apiClient)
export const endpointIds = EndpointIDs.create(apiClient)

The apiHooks constant above now contains a library of React hooks contained within an object structure that matches the controller/endpoint structure of your API Client.

NOTE: The endpointIds constant is a library of strictly types identifiers designed for use with some of API Hooks' more advanced features (such as mock endpoints and refetch queries.) It's not required for the basic hooks to work, so feel free to add it later if/when you need it.