Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

api-contract

/api-contract

Projektuje i sprawdza publiczne REST API jako kontrakt: OpenAPI z bramkami zgodności, wersjonowaniem, kursorami i kluczami idempotencji.

Repozytorium
skills ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
08.11.2026

Ocena i bezpieczeństwo

100/ 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ść35 / 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
3
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
22
Przestarzałość

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

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Projektuje i sprawdza publiczne REST API jako kontrakt: OpenAPI z bramkami zgodności, wersjonowaniem, kursorami i kluczami idempotencji.

Oryginalny opis (EN)

Designs and reviews public REST APIs as a contract: OpenAPI with drift and breaking-change gates, versioning, public IDs only, RFC 9457 errors, cursor pagination, Idempotency-Key on POST, per-token rate limits, Deprecation and Sunset headers, scoped tokens, parity with UI, Terraform and MCP, an API changelog. Use when adding or changing an endpoint or API field. Not for MCP tools or GraphQL.

Jak działa

  1. Applies when / does not apply
  2. Rules
  3. Procedure
  4. Traps
  5. Done when
  6. References
  7. Sources
Sekcje z nagłówków SKILL.md, w oryginale · 182 linii, 2 123 słów
Podgląd SKILL.md
---
name: api-contract
description: "Designs and reviews public REST APIs as a contract: OpenAPI with drift and breaking-change gates, versioning, public IDs only, RFC 9457 errors, cursor pagination, Idempotency-Key on POST, per-token rate limits, Deprecation and Sunset headers, scoped tokens, parity with UI, Terraform and MCP, an API changelog. Use when adding or changing an endpoint or API field. Not for MCP tools or GraphQL."
license: Apache-2.0
metadata:
  author: "Rene Roscher"
---

# API contract

This skill decides what a public REST API promises its consumers and how the build keeps that promise: the shape
of resources, errors, lists, retries, limits and change over time. Framework syntax stays with the vendor docs and
the references below. Identifier format belongs to `dual-key-identifiers`, token permissions to
`authorization-rbac`, the agent surface to `mcp-server-design`. The failure this prevents: a field rename or a
changed error shape that breaks scripts, Terraform plans and integrations without anyone noticing before
customers do.

## Applies when / does not apply

- Applies: a new or changed public endpoint, field, filter, error, status code, header or list; API tokens and
  scopes; rate limits on the public API; a deprecation; the OpenAPI document; a Terraform provider or SDK built on
  the API; a feature that ships in the UI and must reach the API.
- Does not apply: MCP tool design (`mcp-server-design`), GraphQL schemas, internal endpoints only the own frontend
  calls (unless they are also public), outgoing webhook payload signing (`egress-and-webhooks`).

## Rules

Most important first. Examples use a booking API: bookings, customers, resources.

- [invariant] The OpenAPI document is the contract and lives in the repository. CI fails when a route exists
  without a spec entry or the other way round, when a response in the test suite does not validate against the
  spec, and when a diff against the last released spec contains a breaking change without a new version. Why:
  hand-maintained docs drift, and a breaking change in a minor release breaks clients silently. Test: rename one
  response field in a serializer; the contract test and the breaking-change diff both go red. Source: oasdiff,
  "Command-line tool to compare and detect breaking changes in OpenAPI specs" (https://github.com/oasdiff/oasdiff);
  OpenAPI Specification (https://spec.openapis.org/oas/latest.html); both verified 2026-11-03.
- [invariant] Breaking changes are defined in writing and need a new major version: removing or renaming a field,
  endpoint or enum value, changing a type or format, making an optional input required, tightening validation,
  changing a status code or error `type`, changing default sort or page size. Adding optional inputs, response
  fields, endpoints and enum values is not breaking, and the docs tell clients to ignore unknown fields and handle
  unknown enum values. Why: without the list every reviewer decides differently. Test: the diff tool's rule set
  matches the list; a fixture spec pair for each item is classified correctly. Source: reproducible with the test
  above.
- [invariant] Resources expose public IDs only: `id` and every reference field are opaque strings, URLs and
  `Location` headers use them, and foreign, missing and malformed IDs give the same 404. Why: sequential IDs
  enumerate records and leak volume. Test: the response-scanning guard from `dual-key-identifiers` runs over the
  API suite. Source: OWASP API Security Top 10 2023, API1
  (https://api-security.owasp.org/editions/2023/en/0xa1-broken-object-level-authorization, verified 2026-11-03).
- [invariant] Every error is `application/problem+json` per RFC 9457 with `type`, `title`, `status`, `detail` and
  `instance` where useful; validation errors add one extension member listing field and message per error. The
  same shape covers 400, 401, 403, 404, 409, 422, 429 and 500, carries no stack trace or SQL, and `type` values are
  stable and documented. Why: clients branch on `type`, not on English text. Test: one test per status asserts the
  media type and members; a forced exception in production mode shows no trace. Source: RFC 9457, "This document
  obsoletes RFC 7807" and the member definitions (https://www.rfc-editor.org/rfc/rfc9457.html, verified
  2026-11-03).
- [invariant] Every list endpoint is paginated with a documented maximum page size, a stable order with a unique
  tiebreaker, and a `next` cursor or link; an unbounded list does not exist. Why: a list that grows with the
  customer becomes a timeout and a memory spike. Test: request with `limit` above the maximum and get the maximum;
  insert rows between pages and see no duplicates or gaps. Source: reproducible with the test above.
- [invariant] Create endpoints accept an `Idempotency-Key` header: the key is scoped to the token, the stored
  record holds a request fingerprint and the response, a reuse with a different payload gets 422, a retry while
  the first request runs gets 409, a replay returns the stored response, and the expiry is documented. Before a
  replay the token's current scopes are checked again. Why: clients that lost a response retry and create
  duplicates. Test: same key and body twice gives one booking and identical responses; same key and different
  body gives 422; revoke the scope and the replay is refused. Source: draft-ietf-httpapi-idempotency-key-header,
  an active Internet-Draft (version 08), not an RFC: 422 for a different payload, 409 while processing, 400 when a
  required key is missing (https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/, verified
  2026-11-03).
- [invariant] Rate limits are keyed by token after authentication, with separate named limiters per surface, and
  a limited request gets 429 with `Retry-After`. Why: a limiter that runs before authentication counts per IP, so
  every customer behind one NAT shares one bucket, and unnamed limiters share one counter across routes. Test:
  assert the middleware order the framework actually executes; two tokens from one IP have separate buckets.
  Source: RFC 6585 §4, 429 "MAY include a Retry-After header" (https://www.rfc-editor.org/rfc/rfc6585.html#section-4,
  verified 2026-11-03).
- [invariant] Tokens carry scopes chosen at creation, a prefix that names the credential class, are stored as a
  hash and shown once; each route checks one scope. Details and rotation are in `authorization-rbac`. Why: a
  recognisable prefix lets secret scanners find leaked tokens, and least privilege limits a leak. Test: a token
  without the scope gets 403 problem details; the database holds no plaintext token. Source: GitHub, "token
  prefixes are a clear way to make tokens identifiable"
  (https://github.blog/engineering/platform-security/behind-githubs-new-authentication-token-formats/, verified
  2026-11-03).
- [invariant] Deprecation is announced in the response: `Deprecation` with a structured date, `Sunset` with an
  HTTP-date not earlier than the deprecation, and a `Link` with `rel="deprecation"` to the notice; usage of
  deprecated endpoints is counted per token so their owners can be told. Why: consumers notice headers in logs and
  tooling, and owners need to be contacted before removal. Test: a deprecated route returns all three headers with
  the dates from the deprecation registry. Source: RFC 9745, "The timestamp given in the Sunset HTTP header field
  MUST NOT be earlier than the one given in the Deprecation header field"
  (https://www.rfc-editor.org/rfc/rfc9745.html); RFC 8594, Sunset "indicates that a URI is likely to become
  unresponsive at a specified point in the future" (https://www.rfc-editor.org/rfc/rfc8594.html); both verified
  2026-11-03.
- [invariant] One write path: API controllers call the same domain services as the UI, the Terraform provider and
  the MCP server; validation bounds come from shared constants that match database constraints. Every writable
  field is readable back in the same shape, and secrets are write-only with a fixed sentinel that means "keep".
  Why: two write paths drift, and a field Terraform can write but not read produces a permanent diff. Test: a
  parity test creates the same booking through the UI action and the API and compares stored state; a provider
  acceptance test applies, then plans, and expects no changes. Source: reproducible with the test above.
- [invariant] Features reach every surface or are listed as gaps: a change that adds a field or action to the UI
  states whether the API, the Terraform provider and the MCP server get it in the same release, and the gaps live
  in one list. Why: customers who automate find missing fields only when their script fails. Test: a CI check that
  each spec change touching a resource also updates the parity list. Source: reproducible with the test above.
- [invariant] Consumers have an API changelog: dated entries, breaking changes and deprecations marked, linked
  from the `Deprecation` notice. A spec diff with changes requires a changelog entry. Why: a spec diff tells
  machines what changed, not people why. Test: a CI check fails when the released spec changes without a new
  changelog entry. Source: reproducible with the test above.
- [default] The major version is in the path (`/v1/`), and only breaking changes create a new one. Trade-off: URLs
  change on a major version, in exchange for versions that are visible in logs, docs and caches. Deviate only with
  an ADR that names this trade-off. Proof: the router has no unversioned public route.
- [default] Cursor pagination with an opaque cursor built from non-sensitive sort columns, for example
  `(created_at, id)` with the public ID. Trade-off: no jump to page N and no exact total by default, in exchange for
  stable pages under inserts and constant cost. Deviate only with an ADR that names this trade-off. Proof: decode a
  cursor; it holds no internal key.
- [default] Filters and sorts are allowlisted per endpoint; unknown query or body parameters on writes give 400 or
  422 instead of being ignored. Trade-off: clients cannot send extra fields, in exchange for typos that fail loudly
  instead of silently doing nothing. Deviate only with an ADR that names this trade-off. Proof: `filter[stauts]`
  returns a problem with the unknown parameter named.
- [default] Send `RateLimit` and `RateLimit-Policy` per draft-ietf-httpapi-ratelimit-headers (version 11, an active
  Internet-Draft), for example `RateLimit: "default";r=50;t=30`. Trade-off: the draft may still change and some
  clients only read older `X-RateLimit-*` names, in exchange for following the format the IETF is standardizing.
  Deviate only with an ADR that names this trade-off. Source:
  https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/, verified 2026-11-03.
- [default] Timestamps are RFC 3339 strings in UTC with `Z`; money is an integer in minor units plus an ISO 4217
  currency code. Trade-off: clients convert for display, in exchange for no time zone or float rounding
  ambiguity. Deviate only with an ADR that names this trade-off. Source: RFC 3339
  (https://www.rfc-editor.org/rfc/rfc3339.html, verified 2026-11-03).

## Procedure

1. Gate: does a client outside the own frontend call this, or will it? If not, stop.
2. Write the spec change first: paths, schemas with public IDs as strings, problem types, examples.
3. Classify the change against the breaking list. Breaking means a new version or a deprecation plan.
4. Implement through the domain service the UI uses; add the parity test.
5. Lists: cursor, maximum page size, allowlisted filters and sorts.
6. Creates: Idempotency-Key handling with fingerprint, 409, 422, scope re-check on replay.
7. Errors: problem details for every status the endpoint can return.
8. Auth and limits: required scope, named limiter keyed by token after authentication.
9. Deprecations: registry entry, headers, usage counter, owner notice.
10. Update the parity list for Terraform and MCP, and add the changelog entry.
11. Run contract tests, the breaking-change diff and the ID guard before review.

## Traps

- A framework's rate-limit middleware moved ahead of authentication by a priority list, so a limit documented per
  token was enforced per IP. Test the executed order, not the declared one.
- An error handler that returns problem details for API routes but HTML for unmatched routes or for exceptions
  thrown in middleware.
- An idempotent replay served from a store before the scope check, so a revoked scope still gets the old response.
- A response field added with `null` for old records breaks clients that typed it as required; document nullability.
- A generated spec that differs per environment because optional packages register routes only in development.
- A Terraform provider that reads a field the API returns in a different format (time zone, casing, ordering of a
  list) shows a diff on every plan.
- A paginated endpoint whose order changes with a new index, which a client sees as duplicates and gaps.

## Done when

- The spec is committed, contract tests validate every response in the suite, and the breaking-change diff runs in
  CI.
- Errors are problem details on every status; lists have a maximum page size and stable order.
- Creates honour `Idempotency-Key` with 409 and 422 and a scope re-check on replay.
- Rate limits are per token after authentication with 429 and `Retry-After`.
- Deprecated routes send `Deprecation`, `Sunset` and `Link`, and usage is counted per token.
- The parity list and the API changelog are updated in the same change.

## References

- [references/http-details.md](references/http-details.md): load when writing problem types, pagination, the
  idempotency store, rate-limit headers or deprecation headers.
- [references/parity-and-tokens.md](references/parity-and-tokens.md): load when wiring the API to the UI's write
  path, building a Terraform provider or SDK on it, or designing tokens and scopes for API consumers.

## Sources

- https://spec.openapis.org/oas/latest.html: OpenAPI Specification, version 3.2.1 at the time of reading, verified
  2026-11-03.
- https://github.com/oasdiff/oasdiff: breaking-change detection for OpenAPI, verified 2026-11-03.
- https://www.rfc-editor.org/rfc/rfc9457.html: problem details, obsoletes RFC 7807, verified 2026-11-03.
- https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/: active Internet-Draft, version 08,
  verified 2026-11-03.
- https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/: active Internet-Draft, version 11,
  verified 2026-11-03.
- https://www.rfc-editor.org/rfc/rfc6585.html#section-4: 429 and `Retry-After`, verified 2026-11-03.
- https://www.rfc-editor.org/rfc/rfc9745.html: `Deprecation` header, Standards Track, March 2025, verified
  2026-11-03.
- https://www.rfc-editor.org/rfc/rfc8594.html: `Sunset` header, Informational, verified 2026-11-03.
- https://api-security.owasp.org/editions/2023/en/0xa1-broken-object-level-authorization: unpredictable IDs and
  object-level checks, verified 2026-11-03.
- https://github.blog/engineering/platform-security/behind-githubs-new-authentication-token-formats/: token
  prefixes for identification and secret scanning, verified 2026-11-03.
- https://www.rfc-editor.org/rfc/rfc3339.html: timestamp format, verified 2026-11-03.
Pliki w paczce (3)
  • SKILL.md 15 KB
  • references/http-details.md 4 KB
  • references/parity-and-tokens.md 3 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · Rene-Roscher/skills100Apache-2.0
jeremylongshore/tons-of-skills-marketplace100MIT
baibesh/devkit-skills100MIT
a-abdellatif98/api-contract-guard100MIT
AmirAzy/HoNspot100MIT

Migawka bazy z 13.11.2026 · wersja paczki 60c9f1d35ad7 (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.
  • 100api-design
    Projektuje i przegląda REST API odporne na ponowienia: nazwy, błędy RFC 9457, stronicowanie, ETag, limity i zmiany łamiące zgodność.
  • 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.
  • 100api-design
    Projektuje kontrakty REST, GraphQL i OpenAPI przed implementacją w podejściu API-first.
  • 100api-design-first
    Tworzy specyfikację OpenAPI 3.1 przed kodem, pilnuje dobrych praktyk REST, wersjonowania, stronicowania, uwierzytelniania i idempotencji.
  • 100api-design
    Projektuje kontrakty API REST i GraphQL: kształt zasobów, wersjonowanie z oknami wycofania, błędy RFC 9457 i specyfikacje OpenAPI.

Uwagi i zgłoszenia

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