Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

node-craft-contract

/node-craft-contract

Ustala zasady kontraktu API backendu Node.js: wersjonowanie REST, OpenAPI, walidację, model błędów i paginację kursorową.

Repozytorium
node-craft ↗
Licencja
MIT
Ostatnia zmiana repozytorium
04.11.2026

Ocena i bezpieczeństwo

90/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść25 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
9
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 04.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

  1. Defaults for a new project
  2. Checklist for an endpoint
Sekcje z nagłówków SKILL.md, w oryginale · 48 linii, 442 słów
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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.