Skip to content

reactive/data-client / .agents/skills/data-client-rest-setup

data-client-rest-setup

Verified

Set up and migrate to @data-client/rest for REST APIs. Detects existing HTTP patterns (axios, fetch, ky, superagent, got) and migrates them. Creates custom RestEndpoint base class with common behaviors. Use when adopting @data-client/rest in a new or existing project.

---
name: data-client-rest-setup
description: Set up and migrate to @data-client/rest for REST APIs. Detects existing HTTP patterns (axios, fetch, ky, superagent, got) and migrates them. Creates custom RestEndpoint base class with common behaviors. Use when adopting @data-client/rest in a new or existing project.
disable-model-invocation: true
---

# REST Protocol Setup & Migration

Setting up `@data-client/rest` only defines endpoints and schemas, so it needs no Data Client provider: leave how the app loads and stores data alone unless the user asks to change it.

APIs: [RestEndpoint](references/RestEndpoint.md), [resource](references/resource.md). Vue projects: read `<name>.vue.md` instead of `<name>.md` when it exists.

## Step 1: Install

Install `@data-client/rest` with the project's package manager. It ships the skills this setup uses next (`data-client-rest`, and `data-client-schema` from `@data-client/endpoint`); link them from the project root:

```bash
npx --no data-client-skills   # pnpm exec data-client-skills, yarn data-client-skills
```

- If a skill isn't available by name afterwards, read `.claude/skills/<skill>/SKILL.md`.
- If the command isn't found, the installed version predates 0.19: run `npx skills add reactive/data-client --skill data-client-rest --skill data-client-schema -y` instead.
- Add this line to `AGENTS.md` (create it if missing; if a `CLAUDE.md` exists, make sure it has an `@AGENTS.md` line), with the project's package manager in the command, and commit `.agents/skills` and `.claude/skills`:

```md
After adding, removing or upgrading `@data-client/*` packages, run `npx --no data-client-skills` and commit the skill links.
```

## Step 2: Migrate each HTTP library

Check `package.json` and imports. Several libraries can coexist: migrate each one's files with its reference. If HTTP calls exist but the library is unclear, ask the user.

| Detected | Follow |
|----------|--------|
| `axios` | [Axios migration](references/axios-migration.md), with the steps below |
| `fetch(` calls or wrappers around fetch | [Fetch migration](references/fetch-migration.md) |
| `ky` | [Ky migration](references/ky-migration.md) |
| `superagent` | [SuperAgent migration](references/superagent-migration.md) |
| `got` | [Got migration](references/got-migration.md) |
| none | Step 3 |

Axios:

1. Check `git status` is clean (commit or ask first), so the codemod's changes can be reviewed on their own.
2. Run the codemod before any manual edits, on the source folders (never the repo root): `npx @data-client/codemods axios-to-rest src/` (it reads TypeScript and skips `node_modules`). It turns each axios call into a call to an endpoint (usually a module-level `const` when the call is in a function), turns each `axios.create()` instance into a base endpoint class, and drops `.data` unless a response interceptor may have unwrapped it.
3. The codemod doesn't format its output, so run the fixers the project already uses on the changed files: its `format` or `lint --fix` script, or the tool its config names (such as `prettier --write`, `eslint --fix` or `biome check --write`).
4. Search the source for `TODO(data-client)`. Each comment names one thing to finish and links its guide section, which is in the reference under the same heading. Resolve it, then delete the comment.
5. Follow the reference's remaining steps. Callers keep loading data the way they did; only the call changes.
6. Run the type checker and tests. When no `axios` import or `TODO(data-client)` comment is left, uninstall axios.

## Step 3: Base endpoint class

Put the project's shared request behavior in one `RestEndpoint` subclass and build every endpoint from it. If a migration made one (the axios codemod does, from `axios.create()`), add to that class instead of creating another.

```ts
import { RestEndpoint, RestGenerics } from '@data-client/rest';

export class BaseEndpoint<O extends RestGenerics = any> extends RestEndpoint<O> {
  urlPrefix = 'https://api.example.com';

  getHeaders(headers: HeadersInit): HeadersInit {
    const token = localStorage.getItem('authToken');
    return { ...headers, ...(token && { Authorization: `Bearer ${token}` }) };
  }
}
```

Override only what the app does today:

| Behavior | Override |
|----------|----------|
| Auth, CSRF or other headers (may be `async`, e.g. token refresh) | `getHeaders(headers)` |
| Auth token from React context (Okta, Auth0) | [`hookifyResource()`](references/hookifyResource.md); a base class can't read context |
| Cookies (axios `withCredentials`), other `RequestInit` | `async getRequestInit(body)` returning `{ ...(await super.getRequestInit(body)), credentials: 'include' }`. Without `await`, the spread drops `method`, `body` and headers, so every mutation is sent as a GET |
| A response interceptor reshapes the body without losing data: unwraps a `{ "data": ... }` with nothing beside it, converts key case | `process(value)`, e.g. `return value?.data` (null for a 204). Fields the app reads, like `meta`, stay in the endpoint's schema |
| Date fields | Not `process()`: the Entity's `static schema`, e.g. `createdAt: Temporal.Instant.from` (skill "data-client-schema") |
| Status handling, like a 401 redirect | `async fetchResponse(input, init)`: `super.fetchResponse()` throws a `NetworkError` for any non-2xx status, so wrap it in `try`, check `error.status` in `catch`, and rethrow ([Server error messages](references/axios-migration.md#server-error-messages) shows it) |
| Arrays or nested objects in the query | `searchToString(searchParams)`, e.g. `qs.stringify(searchParams, { arrayFormat: 'brackets' })` |
| Non-JSON responses (files, text) | The [`content`](references/RestEndpoint.md#content) option, e.g. `content: 'blob'`; otherwise `parseResponse(response)` |

Request bodies need no override: a plain object or array is sent as JSON, and anything else (`FormData`, `URLSearchParams`, a string) as-is ([getRequestInit](references/RestEndpoint.md#getRequestInit)).

## Defining endpoints

**`resource()`** for standard CRUD on one path (`get`, `getList`, `getList.push`, `update`, `partialUpdate`, `delete`):

```ts
export const TodoResource = resource({
  path: '/todos/:id',
  schema: Todo,
  Endpoint: BaseEndpoint,
});
```

**`new BaseEndpoint({ ... })`** for anything else (search, auth, custom actions). Type a body with a truthy value, `body: {} as { email: string; password: string }`, never `undefined as unknown as T`: `body: undefined` means the endpoint sends no body. Every method but `GET` and `DELETE` (including `HEAD` and `OPTIONS`) sends a body unless it sets that `body: undefined`, so one that sends none needs it, or its only argument is taken as the body and the path params go missing. A `DELETE` sends a body only when it has `body`, such as `body: {} as { ids: string[] }`, including one inherited through `extend()`: set `body: undefined` on a `DELETE` extended from an endpoint with a body.

If the codebase validates responses with Zod or Yup, keep that by parsing in `process()` and still add an Entity `schema`; see "Coexisting with Zod or Yup" in the [Axios migration](references/axios-migration.md).

## Next steps

1. Define Entity classes (skill "data-client-schema") and set each endpoint's `schema:`. Without one, responses aren't normalized or cached.
2. Apply skill "data-client-rest" for resource and endpoint patterns.
3. Only when the user asks to move components onto the store: apply skill "data-client-react" or "data-client-vue".

Auth on the base endpoint: [Authentication](references/auth.md); with a Django backend,
[Django REST Framework](references/django.md) (CSRF header).
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 321kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 321kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 321kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 321kUpdated Claude CodeCodexVerifiedInstall