Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

api-design

/api-design

Projektuje interfejsy odporne na zmiany po stronie konsumentów: model zasobów, błędy, wersjonowanie, paginacja i zgodność wsteczna.

Repozytorium
headcount ↗
Licencja
MIT
Ostatnia zmiana repozytorium
18.10.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
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 18.10.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

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

  1. Model the domain, not the database
  2. Errors are part of the contract
  3. Compatibility
  4. Pagination, filtering and limits
  5. Sources
  6. Tooling
  7. Never
Sekcje z nagłówków SKILL.md, w oryginale · 75 linii, 545 słów
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

RepozytoriumWynikLicencja
Ta strona · cbrock84/headcount90MIT
proyecto26/system-design-skills100MIT
ericrisco/rsc-harness100MIT
Sanit-mann/The-Insectoids100MIT
yonatangross/orchestkit100MIT
travisjneuman/.claude100MIT
wrongstack/wrongstack100MIT
jelvodev/yaap100MIT
komluk/scaffolding100MIT

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.

Uwagi i zgłoszenia

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