node-craft-contract
/node-craft-contract
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
- Author
- hasaneks ↗
- Repository
- node-craft ↗
- Licence
- MIT
- Last repository change
- 04.11.2026
Assessment and security
- Files in this package
- 9
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 04.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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
Original author 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 head
How it works
- Defaults for a new project
- Checklist for an endpoint
SKILL.md preview
---
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`.
Files in this package (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
Versions
The database has no other skills named node-craft-contract.
Database snapshot: 13.11.2026 · package version d1069fb00e11 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100api-design
Designs a REST or async event contract: resources, status codes, one error model, pagination, versioning, idempotency, tenant path, OpenAPI spec. Use for \"design an endpoint/API/event\", reviewing a contract, or planning a breaking change. - 100common-api-design
Apply REST API conventions — HTTP semantics, status codes, versioning, pagination, and OpenAPI standards for any framework. Use when designing endpoints, choosing HTTP methods, implementing pagination, or writing OpenAPI specs. - 100design-http-api
Use when adding or changing HTTP endpoints, or when the frontend needs typed calls — sets the OpenAPI 3.1 contract, RFC 9457 errors, cursor pagination, idempotency keys, versioning, and a generated typed client behind the frontend fetcher seam. - 100common-api-design
Apply REST API conventions — HTTP semantics, status codes, versioning, pagination, and OpenAPI standards for any framework. Use when designing endpoints, choosing HTTP methods, implementing pagination, or writing OpenAPI specs. - 100api-design
Design or review an HTTP API as a contract (resources, status codes, one error shape, pagination, idempotent writes, versioning). Use it whenever you add or change an endpoint, a field or an error format, write an OpenAPI document, or need to know whether a change breaks clients. - 100api-design-expert
Expert API design for REST & GraphQL: resource modeling, status codes, versioning, pagination, idempotency, errors, and contracts. Trigger keywords: API design, REST, RESTful, GraphQL, OpenAPI, endpoint, status code, versioning, pagination, cursor, idempotency, rate limit,…