useApiClient
Hook that returns a typed client for your app’s own API, generated from the handler files. Each function returns exactly what the handler returned.
Usage
import { useParams } from "react-router-dom";
import { useApiClient } from "app/api";
import { useRequest } from "app/hooks";
export default function OrderPage() {
const { id } = useParams();
const api = useApiClient();
const { data: order } = useRequest(() => api.orders.detail(Number(id)), { refreshDeps: [id] });
return <h1>Order {order?.id}</h1>;
}useApiClient is a hook: call it at the top of a component, not inside an event handler or a loop.
Signature
export type ApiClient = ReturnType<typeof buildClient>;
export function useApiClient(): ApiClient;manh.run regenerates app/api.ts on every build. Don’t edit it.
Parameters
None.
Returns
An object with one function per handler file. Function names come from the file path:
app/orders/get.ts→api.orders.list(params?)app/orders/post.ts→api.orders.create(body)app/orders/[id:int]/get.ts→api.orders.detail(id)app/orders/[id:int]/patch.tsorput.ts→api.orders.update(id, body)app/orders/[id:int]/delete.ts→api.orders.remove(id)app/orders/[id:int]/approve/post.ts→api.orders.approve(id, body)app/classes/[id:int]/attendance-export/get.tsdeclaringschema = { query }→api.classes.attendanceExport(id, params?)app/reports/sales/get.ts→api.reports.sales(params?)- Every static folder after the resource is a group, and path params become arguments in order:
app/courses/[id:int]/assistants/[instructorId:int]/delete.ts→api.courses.assistants.remove(id, instructorId). Addapp/courses/[id:int]/assistants/post.tsand it joins the same group:api.courses.assistants.post(id, body) - Dashed folders become camelCase:
app/chat-messages/get.ts→api.chatMessages.list() put,patchanddeletewithout an id keep the method name:app/settings/put.ts→api.settings.put(body)- A sub-folder with several handlers becomes a group, each handler under its CRUD name:
app/me/prefs/get.ts+app/me/prefs/patch.ts→api.me.prefs.list()+api.me.prefs.patch(body) - Two handlers that still want one name (
[id:int]/put.ts+[id:int]/patch.ts) are acheckerror,code.api-name-collision, naming both files. Keep one, or move one into its own sub-folder (app/orders/[id:int]/reprice/patch.ts→api.orders.reprice(id, body)).
Path parameters accept string | number. GET and DELETE functions without an id take params (the query string); with an id they take params after the id when the handler declares query in its schema; POST, PUT and PATCH take body. Every write (POST, PUT, PATCH, DELETE) takes an optional last argument opts?: ApiCallOptions, which holds idempotencyKey for now.
Each function returns a Promise of exactly what the handler returned: list handlers return { data, total }, detail, create and update handlers return the row. Don’t add .data.
When the server answers with an error, the promise rejects with an axios error; the error body is at e.response.data as { error, message, code }. manh.run’s busy answers add retryable, retryAfterSeconds and requestId (see Error codes).
Examples
Feeding the client to a hand-written ProTable:
<ProTable<Order> rowKey="id" columns={orderColumns} request={tableRequest(api.orders.list)} />tableRequest turns the table’s paging, sorting, filters and search box into the list endpoint’s query.
- After signIn, every call sends
Authorization: Bearer <token>. Don’t add the header yourself. - Calling a function that isn’t in the client is a
checkerror. Readapp/api.tsfor the real names. - The client runs on the same axios instance as useApi, so reads that get a busy answer retry and an expired session goes back to
/loginhere too. - Writes retry only with an
idempotencyKey. Keep one key per submit (also when the user clicks again on a slow network), and change it once the call went through:
const key = useRef(crypto.randomUUID());
await api.orders.create(values, { idempotencyKey: key.current });
key.current = crypto.randomUUID(); // sent: the next submit is a new orderThe key reaches the handler as the Idempotency-Key header. A handler that must never write twice stores the key with the row (a unique column) and returns the existing row when the key comes back.
Next steps
- API handlers: what the handler returns is what the client gets.
- useRequest: call the client when the page opens and keep
data,loading. - submit: send forms through the client.