Skill Wiki
api-design
Domain inferred from 11 atoms across the corpora.
Atom counts by kind
| Kind | Count |
|---|---|
| type | 2 |
| anti-pattern | 1 |
| fact | 1 |
| feedback | 1 |
| pattern | 1 |
| principle | 1 |
| rule | 1 |
| scope | 1 |
| term | 1 |
| tradeoff | 1 |
Sample atoms
Rpc As Rest
An API that uses HTTP+JSON but ignores REST semantics: verb-in-URL paths, status codes that don't match operations, GET with side effects, POST for everything.…
Http Method Semantics
RFC 9110 §9 defines HTTP method properties: GET (read; safe + idempotent + cacheable). HEAD (read metadata only; safe + idempotent + cacheable).…
Feedback Api Versioning Pain
Accumulated feedback from teams who shipped a public REST API and lived through 2+ major versions. Captures the pain points that did not appear in v1 design but emerged once the contract was real and consumers existed.
Cursor Pagination
Cursor-based pagination uses an opaque cursor (typically encoding a sort key + tiebreaker id) to mark a position in a sorted collection.…
Pagination First
List endpoints (GET /collection) MUST return paginated responses with: (1) a default page size (commonly 20–50, never unbounded); (2) a maximum page size enforced server-side (e.g.…
Resource Not Action
Every URL path is a noun phrase identifying a resource or collection. State changes occur via HTTP methods: GET (read), POST (create), PUT (full replace), PATCH (partial update), DELETE (remove).…
Scope Public Api
Defines applicability for atoms whose guidance applies only to public API surfaces — endpoints exposed beyond the controlling team.…
Idempotency Key
A client-supplied unique identifier (typically a UUID v4 or business-event id) attached to a non-idempotent request (POST, PATCH) that allows the server to safely deduplicate retries.…
Rest Vs Graphql
Choosing between REST (resource-oriented, HTTP-native) and GraphQL (query-oriented, schema-flexible) for a new API.…
Type Error Shape
Schema for an error response body in a JSON API. Based on RFC 9457 (Problem Details for HTTP APIs, July 2024) — the IETF-standard error format that supersedes RFC 7807.…
Type Pagination Cursor
Schema for a paginated response envelope. Carries the data array, has-more boolean, opaque cursor for fetching the next page, and optional total count.…