data-client-rest_skill

Overview

This skill defines and manages REST resources using @data-client/rest to model endpoints, normalize responses, and handle CRUD operations with TypeScript type safety. It provides patterns for resource(), RestEndpoint, URL templating, search params, optimistic updates, pagination, and cache-aware fetches. Use it to generate consistent, normalized API layers for React or React Native apps.

How this skill works

You declare a resource with resource() or a single endpoint with RestEndpoint, supplying a typed path (path‑to‑regexp), schema for normalization, and optional urlPrefix, searchParams, paginationField, and optimistic flag. The library builds typed methods like get, getList, update, partialUpdate, push, unshift, delete, and getPage; each call composes a URL, performs fetch, parses the response, normalizes entities into the cache, and returns typed data. Mutations can provide optimistic responses and integrate with the controller to update cache and revalidate automatically.

When to use it

• You need normalized entities and automatic cache management across components.
• Creating full CRUD resources for a RESTful collection with typed path params.
• Defining single custom endpoints (polling, non-CRUD) with RestEndpoint.
• Implementing optimistic UI updates for faster user feedback.
• Adding typed query/search parameters or pagination to list endpoints

Best practices

• Always attach a schema for each resource or endpoint to enable normalization and cache updates.
• Prefer resource() for collections with standard CRUD and RestEndpoint for standalone or non-CRUD endpoints.
• Use typed path templates and searchParams generics to make calls fully type-safe.
• Enable optimistic only when you can compute a safe optimistic response; implement getOptimisticResponse to derive updates from the cache snapshot.
• Use urlPrefix for absolute hosts (APIs, CDNs) and keep path as path‑to‑regexp templates for predictable URL building.

Example use cases

• Define a TodoResource with schema, urlPrefix and paginationField to drive list rendering and infinite scroll.
• Create a Ticker RestEndpoint with pollFrequency for live market tickers.
• Use getList.push/unshift for server-side POSTs that append or prepend items in normalized collections.
• Implement partialUpdate/update to PATCH/PUT a resource and let cache reconcile changes automatically.
• Extend a base resource with .extend() to add a custom search endpoint or override a path.