api-design
/api-design
Projektuje interfejsy odporne na zmiany po stronie konsumentów: model zasobów, błędy, wersjonowanie, paginacja i zgodność wsteczna.
- Autor
- cbrock84 ↗
- Repozytorium
- headcount ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 18.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 18.10.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
Projektuje interfejsy odporne na zmiany po stronie konsumentów: model zasobów, błędy, wersjonowanie, paginacja i zgodność wsteczna.
Oryginalny opis (EN)
Designs interfaces that survive their consumers — resource modeling, errors, versioning, pagination, and compatibility. Use this to design a new API, review one before it ships, decide how to version or deprecate, fix an interface consumers keep misusing, or work out whether a change is breaking.
Jak działa
- Model the domain, not the database
- Errors are part of the contract
- Compatibility
- Pagination, filtering and limits
- Sources
- Tooling
- Never
Podgląd SKILL.md
--- name: api-design description: Designs interfaces that survive their consumers — resource modeling, errors, versioning, pagination, and compatibility. Use this to design a new API, review one before it ships, decide how to version or deprecate, fix an interface consumers keep misusing, or work out whether a change is breaking. --- # API design An API is a promise you cannot withdraw once someone depends on it. Design accordingly: the cost of getting it wrong is paid continuously by everyone who integrates. ## Model the domain, not the database Expose concepts the consumer thinks in. An interface that mirrors internal table structure leaks implementation, breaks whenever storage changes, and forces consumers to reconstruct meaning you already had. Name things as the domain names them. Consistency in naming, casing, date formats and identifier style matters more than any individual choice being optimal — an interface that is uniformly imperfect is learnable, and one that is inconsistently excellent is not. ## Errors are part of the contract Most integrations spend most of their code on failure. Give it the same care as the success path: - **Distinguish machine-readable code from human-readable message.** Consumers branch on the code; the message is for the developer reading logs. - **Say what to do about it.** Retryable or not, and after how long. - **Never leak internals** — stack traces and SQL in error bodies are a security finding as well as bad design. - **Be consistent about which failures are which status.** Validation, authorization, and conflict are different situations and should never share a shape. ## Compatibility Adding an optional field is safe. Removing a field, renaming one, tightening validation, changing a default, or adding a required parameter are all breaking, and the last three break consumers who are doing nothing wrong. Version when you must break, and be explicit about how long the previous version lives. A deprecation without a date is a deprecation nobody acts on. Prefer expansion over versioning where possible: a new optional field costs a consumer nothing, a new version costs them a migration. ## Pagination, filtering and limits Any collection that can grow needs pagination from the first release — retrofitting it is a breaking change to every consumer. Prefer cursors over offsets for anything that changes while being read; offset pagination silently skips and duplicates records under concurrent writes. State rate limits in the contract and communicate them in responses. An undocumented limit is discovered in the consumer's production incident. ## Sources `references/sources.md` in this skill lists the outside authorities that settle the questions here — what each one is authoritative for, and what you may do with it. Check them before answering on anything they cover, and cite what you used. Most are free to read and not free to reproduce; the use note on each is binding. ## Tooling Specification and documentation: OpenAPI with Redocly, Stoplight, or Scalar; gRPC with protocol buffers where the consumers are internal services, and similar. Design review and testing: Postman, Insomnia, Bruno, and similar. Contract testing — Pact and similar — is what catches a breaking change before a consumer does. Generate the documentation from the specification and the specification from or alongside the code. Hand-maintained API documentation is wrong within a release, and being confidently wrong is worse for a consumer than being absent. ## Never - Expose internal identifiers or storage structure through the interface. - Return errors whose meaning must be inferred from the message text. - Tighten validation on an existing endpoint and call it non-breaking. - Ship a collection endpoint without pagination.
Pliki w paczce (2)
- SKILL.md 4 KB
- references/sources.md 2 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · cbrock84/headcount | 90 | MIT |
| proyecto26/system-design-skills | 100 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| Sanit-mann/The-Insectoids | 100 | MIT |
| yonatangross/orchestkit | 100 | MIT |
| travisjneuman/.claude | 100 | MIT |
| wrongstack/wrongstack | 100 | MIT |
| jelvodev/yaap | 100 | MIT |
| komluk/scaffolding | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki de714b97a0cb (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
- 100contract-design
Projektuje kontrakt API, zdarzeń lub schematu z naciskiem na zgodność: strategia wersjonowania, zgodność wsteczna, ścieżka migracji konsumentów i semantyka błędów, wraz z listą wpływu na konsumentów. - 90api-contracts
Projektuje lub zmienia kontrakt API dla nowych i istniejących klientów: endpointy, schematy, błędy, uwierzytelnianie i wersjonowanie. - 100api-design-document
Projektuje gotową do produkcji specyfikację API zgodną z OpenAPI 3.1: modelowanie zasobów, kontrakty, uwierzytelnianie, wersjonowanie, błędy, limity i paginacja. - 100rest-api-design
Projektuje lub sprawdza kontrakty HTTP API: zasoby, operacje, statusy i błędy, stronicowanie, zgodność oraz wersjonowanie. - 90dev-api-contract-review
Projektuje lub przegląda kontrakty API: uwierzytelnianie, paginację, wersjonowanie, błędy, zgodność oraz kształt OpenAPI lub GraphQL. - 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.