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.

references/got-migration.md

View on GitHub
# Got → @data-client/rest Migration

## Detection

- `"got"` in `package.json` dependencies (typically Node.js server-side only)
- `import got from 'got'` in source

Search patterns:
- `import.*from ['"]got['"]` — import statements
- `got\(` or `got\.(get|post|put|patch|delete)` — direct calls

> **Note**: Got is a Node.js-only HTTP library. If migrating a server-rendered app (Next.js API routes, Express handlers), these endpoints may only run server-side.

## Migration Rules

### Basic requests

```ts
// Before: got
import got from 'got';
const users = await got('https://api.example.com/users', {
  headers: { Authorization: `Bearer ${token}` },
  searchParams: { page: 1 },
}).json<User[]>();

// After: RestEndpoint (auth moves to a base class)
import { RestEndpoint } from '@data-client/rest';
import { User } from './User';

export const getUsers = new RestEndpoint({
  urlPrefix: 'https://api.example.com',
  path: '/users',
  searchParams: {} as { page?: number },
  schema: [User],
});
```

### Key conversions

| Got pattern | RestEndpoint equivalent |
|-------------|----------------------|
| `prefixUrl` | `urlPrefix` |
| `headers` option | `getHeaders()` |
| `searchParams` | `searchParams` type (same concept, different runtime) |
| `hooks.beforeRequest` | `getHeaders()` or `getRequestInit()` |
| `hooks.afterResponse` | `process()` in the base class |
| `hooks.beforeError` | `fetchResponse()` override |
| `.json<T>()` | Automatic — RestEndpoint parses JSON by default |
| `retry` (got retries by default) | Delete it: Data Client has no retry loop, and a failed request is fetched again when a component next needs it after `errorExpiryLength` (default 1 second). Tell the user that automatic retries are dropped |
| `timeout` | `AbortSignal.timeout(ms)` in a `getRequestInit()` override, so each request gets its own timer ([Timeout](axios-migration.md#timeout)); a `signal` option would start one timer when the endpoint is created |
| `responseType: 'json'` | Default behavior |
| `responseType: 'buffer'` | `parseResponse()` override with `response.arrayBuffer()` |

### Got instance → base class

```ts
// Before: got instance with shared config
import got from 'got';

const api = got.extend({
  prefixUrl: 'https://api.example.com',
  headers: { Authorization: `Bearer ${token}` },
  hooks: {
    beforeRequest: [
      options => {
        options.headers['X-Request-Id'] = generateId();
      },
    ],
    afterResponse: [
      (response) => {
        logResponse(response.statusCode);
        return response;
      },
    ],
  },
});

const users = await api('users').json<User[]>();

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

  getHeaders(headers: HeadersInit) {
    return {
      ...headers,
      Authorization: `Bearer ${token}`,
      'X-Request-Id': generateId(),
    };
  }

  async parseResponse(response: Response) {
    const result = await super.parseResponse(response);
    logResponse(response.status);
    return result;
  }
}
```

### Error handling

```ts
// Before
import { HTTPError } from 'got';
try { ... } catch (err) {
  if (err instanceof HTTPError) {
    console.log(err.response.statusCode);
    console.log(err.response.body);
  }
}

// After
import { NetworkError } from '@data-client/rest';
try { ... } catch (err) {
  if (err instanceof NetworkError) {
    console.log(err.status);
    const body = await err.response.json();
  }
}
```

### Pagination

```ts
// Before: got pagination
import got from 'got';
const allUsers = await got.paginate.all('https://api.example.com/users', {
  pagination: {
    transform: (response) => JSON.parse(response.body),
    paginate: ({ currentItems, response }) => {
      const next = response.headers.link?.match(/<([^>]+)>; rel="next"/)?.[1];
      return next ? { url: new URL(next) } : false;
    },
  },
});

// After: use paginationField or getPage
const UserResource = resource({
  path: '/users',
  schema: User,
  paginationField: 'cursor',
});
// ctrl.fetch(UserResource.getList.getPage, { cursor: nextCursor })
```

## Reference

- [RestEndpoint API](https://dataclient.io/rest/api/RestEndpoint) — lifecycle methods reference
- [NetworkError](https://dataclient.io/rest/api/RestEndpoint#fetchResponse) — error class
- [Pagination guide](https://dataclient.io/rest/guides/pagination) — cursor/offset pagination patterns
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: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated 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: 319kUpdated 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: 319kUpdated Claude CodeCodexVerifiedInstall