data-client-rest-setup_skill

Overview

This skill sets up @data-client/rest for REST APIs and creates a project-wide RestEndpoint base class with common behaviors like auth, urlPrefix, and error handling. It runs after REST patterns are detected and scaffolds a BaseEndpoint tailored to your project's URL, headers, and response conventions. The result is a single place to centralize request/response transforms and lifecycle hooks for all REST endpoints.

How this skill works

The skill installs @data-client/rest (or ensures it is present) and generates a BaseEndpoint TypeScript file that extends RestEndpoint. It inspects the codebase for base URLs, auth patterns, content types, error shapes, and query param conventions, then wires sensible defaults (urlPrefix, getHeaders, getRequestInit, process, parseResponse, searchToString). It also offers common lifecycle overrides like async token refresh, CSRF handling, and custom error handling for status codes.

When to use it

• You have REST-style endpoints detected by a prior data-client setup step.
• You want a centralized place to add auth, CSRF, or token refresh logic.
• You need consistent request/response transforms across many endpoints.
• You use special query serialization (nested objects, arrays) or non-JSON responses.
• You plan to reuse the same header and error handling logic across resources.

Best practices

• Keep BaseEndpoint small and focused: auth, urlPrefix, and parsing helpers only.
• Prefer async getHeaders that handles token refresh, not ad-hoc header changes in each endpoint.
• Unwrap API envelopes in process() so schemas and consumers receive normalized data.
• Use searchToString with qs for nested query params when necessary.
• Handle non-JSON responses in parseResponse and surface meaningful errors from fetchResponse.

Example use cases

• Generate src/api/BaseEndpoint.ts with urlPrefix from process.env and Authorization header pulled from storage or a refresh helper.
• Implement getRequestInit to include credentials: 'include' for cookie-based auth and add CSRF headers.
• Override process() to unwrap { data: ... } envelopes before normalization with normalizr.
• Customize searchToString to use qs.stringify({ arrayFormat: 'brackets' }) for nested query params.
• Intercept 401 responses in fetchResponse to emit an auth:expired event or trigger a refresh workflow.