Skip to content
Skills Library
Programming · Building & coding

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

Repository
node-craft ↗
Licence
MIT
Last repository change
04.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
9
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 04.11.2026, without references to retired models or APIs.

Licence

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

  1. Defaults for a new project
  2. Checklist for an endpoint
Original SKILL.md headings · 48 lines, 442 words
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,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.