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/superagent-migration.md

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

## Detection

- `"superagent"` in `package.json` dependencies
- `import request from 'superagent'` or `require('superagent')` in source

Search patterns:
- `import.*from ['"]superagent['"]` — import statements
- `require\(['"]superagent['"]\)` — CommonJS require
- `\.(get|post|put|patch|del|delete)\(` — chained method calls (context: superagent import)

## Migration Rules

### Basic requests

```ts
// Before: superagent
import request from 'superagent';
const res = await request
  .get('https://api.example.com/users')
  .set('Authorization', `Bearer ${token}`)
  .query({ page: 1 });
const users = res.body;

// 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

| SuperAgent pattern | RestEndpoint equivalent |
|-------------------|----------------------|
| `.set(name, value)` headers | `getHeaders()` |
| `.query(params)` | `searchParams` type |
| `.send(body)` | `body` type on endpoint |
| `.use(plugin)` | Lifecycle method overrides |
| Chained `.get()/.post()` etc. | `method` option |
| `.type('json')` / `.accept('json')` | Automatic — JSON is default |
| `.withCredentials()` | `getRequestInit()` with `credentials: 'include'` |
| `.timeout({ response, deadline })` | `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 |
| `.retry(count)` | 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 |
| `res.body` | Automatic — RestEndpoint returns parsed JSON |
| `res.status` | Available on `NetworkError.status` for error cases |

### Shared config via agent/plugin → base class

```ts
// Before: superagent with shared config
import request from 'superagent';
import prefix from 'superagent-prefix';

const api = request.agent()
  .use(prefix('https://api.example.com'))
  .set('Authorization', `Bearer ${getToken()}`);

const res = await api.get('/users').query({ role: 'admin' });

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

  getHeaders(headers: HeadersInit) {
    return {
      ...headers,
      Authorization: `Bearer ${getToken()}`,
    };
  }
}

export const getUsers = new ApiEndpoint({
  path: '/users',
  searchParams: {} as { role?: string },
  schema: [User],
});
```

### POST / mutation patterns

```ts
// Before
const res = await request
  .post('https://api.example.com/users')
  .send({ name: 'Alice', email: 'alice@example.com' });

// After
export const createUser = new RestEndpoint({
  path: '/users',
  method: 'POST',
  schema: User,
});
```

### Error handling

```ts
// Before
try {
  const res = await request.get('/api/users');
} catch (err) {
  if (err.status) {
    console.log(err.status, 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();
  }
}
```

### File uploads

```ts
// Before
await request
  .post('/upload')
  .attach('file', blob, 'photo.jpg')
  .field('description', 'My photo');

// After — use FormData with RestEndpoint
const uploadFile = new RestEndpoint({
  path: '/upload',
  method: 'POST',
  body: {} as FormData,
  schema: undefined,
});
// Usage: ctrl.fetch(uploadFile, formData)
```

## Reference

- [RestEndpoint API](https://dataclient.io/rest/api/RestEndpoint) — lifecycle methods reference
- [NetworkError](https://dataclient.io/rest/api/RestEndpoint#fetchResponse) — error class
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