node-craft-contract
/node-craft-contract
Ustala zasady kontraktu API backendu Node.js: wersjonowanie REST, OpenAPI, walidację, model błędów i paginację kursorową.
- Autor
- hasaneks ↗
- Repozytorium
- node-craft ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 04.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 9
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 04.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Ustala zasady kontraktu API backendu Node.js: wersjonowanie REST, OpenAPI, walidację, model błędów i paginację kursorową.
Oryginalny opis (EN)
API contract rules for a Node.js backend and every client that calls it: REST resources and versioning, OpenAPI from a single schema source, runtime request/response validation, the success envelope and 204, the error model with stable codes and localized messages, HTTP status mapping (400/401/403/404/409/429/503), the locale header and resolution order, cursor pagination, Idempotency-Key semantics, auth and session outcomes, number/money/date representation, and backward compatibility with old mobile clients. Use when adding or changing an endpoint, its schema, error codes, pagination or head
Jak działa
- Defaults for a new project
- Checklist for an endpoint
Podgląd SKILL.md
---
name: node-craft-contract
description: "API contract rules for a Node.js backend and every client that calls it: REST resources and versioning, OpenAPI from a single schema source, runtime request/response validation, the success envelope and 204, the error model with stable codes and localized messages, HTTP status mapping (400/401/403/404/409/429/503), the locale header and resolution order, cursor pagination, Idempotency-Key semantics, auth and session outcomes, number/money/date representation, and backward compatibility with old mobile clients. Use when adding or changing an endpoint, its schema, error codes, pagination or headers, generating OpenAPI or client types, or integrating a web, admin or mobile client (React Native with or without rn-craft). Client technology is never required."
---
# Design the API contract
The contract is the versioned OpenAPI document plus the documented behaviour behind it. Clients integrate against
that, never against backend entities, ORM models or framework DTO classes. Follow `node-craft` for TDD and done.
| Area | Read |
|---|---|
| Resources, schemas, validation, OpenAPI source, success shape | `references/openapi-validation.md` |
| Error body, codes, status mapping, retry semantics | `references/errors.md` |
| `X-App-Locale`, resolution order, `Content-Language`, caching | `references/locale-contract.md` |
| Cursor pagination, limits, sorting, filters | `references/pagination.md` |
| `Idempotency-Key`, offline writes, client retries | `references/idempotency-contract.md` |
| 401/403 outcomes, identity mapping, sessions, account deletion, push tokens | `references/auth-session-contract.md` |
| Versioning, old clients, breaking changes, enums | `references/versioning.md` |
| Generated client types, monorepo vs separate repos, web and mobile integration, rn-craft | `references/client-integration.md` |
## Defaults for a new project
An existing project's contract wins; extend it compatibly instead (`node-craft` → `references/existing-project.md`).
- REST, resource-oriented paths under `/api/v1`. Another style (GraphQL, RPC) only for a concrete need.
- **One schema source.** Either code-first (route schemas generate OpenAPI) or schema-first (OpenAPI generates
validators and types). Never two hand-maintained sources that can drift.
- **Runtime validation** of body, params, query and required headers. TypeScript types are not validation.
- **Response schemas** list the fields returned. Never serialize an ORM object.
- Success: `{ "data": ..., "meta"?: ... }`. `204 No Content` has no body.
- Errors: `{ "error": { "code", "message", "details"? }, "locale", "requestId" }` with the right HTTP status. Never
`200` with `success: false`.
- Machine values (error codes, field paths, enum values) never change with the language. Clients branch on `code`,
never on `message`.
- Locale: `X-App-Locale` → verified profile preference → `Accept-Language` → `en`.
- Lists: cursor pagination, default 20, max 100, stable sort with a unique tie-breaker.
- Critical creating writes accept `Idempotency-Key`.
- Precision is never lost: money as decimal strings or integer minor units with a currency; integers beyond 2^53 as
strings; instants as ISO 8601 with offset; calendar dates as `YYYY-MM-DD`.
## Checklist for an endpoint
1. Write the contract first: path, method, auth, request schema, response schema per status, error codes, headers
(locale, idempotency, `Retry-After`), pagination.
2. Red: an API test (`inject`) for the success case and each error case, including 401, 403/404 for another user's
resource, 400 with field details, and 409/429 where they apply.
3. Green with schemas wired into the framework so validation, serialization and OpenAPI come from the same place.
4. Regenerate OpenAPI; a CI check fails when the committed spec and the generated spec differ.
5. Check compatibility: would a client built against the previous spec still work? If not, follow
`references/versioning.md`.
Pliki w paczce (9)
- SKILL.md 4 KB
- references/auth-session-contract.md 3 KB
- references/client-integration.md 4 KB
- references/errors.md 5 KB
- references/idempotency-contract.md 3 KB
- references/locale-contract.md 3 KB
- references/openapi-validation.md 4 KB
- references/pagination.md 2 KB
- references/versioning.md 2 KB
Wersje
W bazie nie ma innych skilli o nazwie node-craft-contract.
Migawka bazy z 13.11.2026 · wersja paczki d1069fb00e11 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100api-design
Projektuje kontrakt REST lub zdarzeń: zasoby, kody statusu, jeden model błędów, stronicowanie, wersje, idempotencję i OpenAPI. - 100common-api-design
Stosuje konwencje REST API: semantykę HTTP, kody statusu, wersjonowanie, paginację i standardy OpenAPI, niezależnie od frameworka. - 100design-http-api
Ustala kontrakt OpenAPI 3.1 dla endpointów HTTP: błędy RFC 9457, paginację kursorową, klucze idempotentności, wersjonowanie i wygenerowanego typowanego klienta za warstwą fetchera frontendu. - 100common-api-design
Stosuje konwencje projektowania REST API: metody HTTP, kody statusu, wersjonowanie, stronicowanie i specyfikację OpenAPI. - 100api-design
Projektuje lub przegląda API HTTP jako kontrakt: zasoby, kody statusu, jeden format błędu, stronicowanie i wersjonowanie. - 100api-design-expert
Wspiera projektowanie i recenzję API REST i GraphQL: modelowanie zasobów, kody statusu, wersjonowanie, paginacja kursorowa, idempotencja, błędy, limity i kontrakty.