cosmix/loom

loom-api-design

Designs RESTful APIs, GraphQL schemas, and RPC interfaces for consistency, usability, and scalability.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/cosmix/loom --skill loom-api-design

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

API Design

Overview

Design intuitive, consistent, evolvable API contracts across REST, GraphQL, and gRPC. Get the resource model, HTTP semantics, error envelope, pagination, and versioning right up front — they are the hardest things to change once clients depend on them.

Design Workflow

  1. Model resources and relationships before URLs; name the nouns, then map operations onto them.
  2. Pick the paradigm: REST (resource CRUD, caching, broad tooling), GraphQL (client-shaped reads, aggregation, mobile), gRPC (internal, low-latency, streaming, strong contracts).
  3. Lock the error envelope, pagination shape, and versioning policy once — reuse everywhere.
  4. Design for change: additive evolution, tolerant readers, deprecation windows.
  5. Write the spec (OpenAPI/SDL/proto) as the source of truth; generate clients/servers from it.

REST

Resource & URL conventions

  • Nouns, plural collections: /users, /users/{id}, /users/{id}/orders. Never verbs in paths (/getUsers is wrong — the method is the verb).
  • Pick one case (snake_case or camelCase) and keep it identical across paths, query params, and bodies.
  • Keep nesting shallow (≤2 levels); deep hierarchies couple resources. Prefer /orders?user_id= over /users/{id}/orders/{oid}/items/....
  • Sub-resource actions that aren't CRUD: model as a resource (POST /orders/{id}/refunds) rather than an RPC verb (POST /orders/{id}/refund) when the action produces a trackable entity.

HTTP methods, safety, idempotency

MethodPurposeSafeIdempotentBody
GETReadyesyesno
HEADRead headersyesyesno
POSTCreate / non-idempotent actionnonoyes
PUTFull replace (client sets full state)noyesyes
PATCHPartial updatenonot inherentlyyes
DELETERemovenoyesmaybe
  • Idempotent = same request repeated yields same server state (not same response — a repeated DELETE may return 404 the second time; that's fine).
  • PUT replaces the entire resource — omitted fields are cleared. If a client can't send full state, use PATCH.

Status codes — get the ambiguous ones right

CodeUse forNot for
200OK with bodycreates (use 201)
201Created; return Location + body
202Accepted, async processing pendingsync completion
204Success, no body (DELETE, some PUT)
400Malformed syntax (bad JSON, wrong type)valid-but-rejected semantics
401Missing/invalid authenticationauthorization failures
403Authenticated but not authorizedmissing auth (401)
404Not found (or hide existence from 403)
409State conflict: duplicate, optimistic-concurrency/version clashfield validation
422Well-formed but semantically invalid (business-rule / field validation)syntax errors (400)
428Precondition Required — force If-Match to prevent lost updates
412Precondition Failed — If-Match/ETag mismatch
429Rate limited; include Retry-After
503Temporarily down; include Retry-After

⚠ 400 vs 422: 400 = "I can't parse this." 422 = "I parsed it, but age: -5 violates a rule." Pick one convention for field-validation errors (422 is the modern default) and apply it everywhere. ⚠ 409 vs 422: 409 is about resource state (email already taken, stale version); 422 is about the payload's semantics.

PATCH: Merge Patch vs JSON Patch

Two incompatible standards — declare which via Content-Type:

  • JSON Merge Patch (RFC 7386, application/merge-patch+json): send a partial object; present keys overwrite, null deletes the member. Simple, but you cannot set a value to null and cannot edit array elements (arrays are replaced wholesale).
  • JSON Patch (RFC 6902, application/json-patch+json): an ordered array of ops (add/remove/replace/move/copy/test) with JSON Pointer paths. Handles arrays, nulls, and conditional updates; verbose. test enables optimistic concurrency inside the patch.
json
// merge-patch: clears "nickname", sets name
{ "name": "Ada", "nickname": null }
// json-patch: equivalent + array edit
[ { "op": "replace", "path": "/name", "value": "Ada" },
  { "op": "remove", "path": "/nickname" },
  { "op": "add", "path": "/tags/-", "value": "vip" } ]

Idempotency keys (safe POST retries)

For non-idempotent creates/payments, accept a client-generated Idempotency-Key header. Store key → (request fingerprint, response) for a window (e.g., 24h). On replay: same key + same body ⇒ return the stored response; same key + different body ⇒ 422/409 (key reuse). Scope keys per endpoint + authenticated principal. This is the correct fix for "user double-clicked / client retried on timeout."

Pagination

StyleProsCons / gotchas
Offset/limit (?page=&per_page=)random access, total counts, trivialdrifts under concurrent writes (inserts/deletes shift the window → skipped or duplicated rows); deep offsets are slow (DB scans+discards N rows)
Cursor/keyset (?after=<opaque>)stable under writes, O(1) via indexed WHERE key > cursorno jump-to-page; needs a stable total-order sort key

⚠ Cursor correctness: the sort key must be unique and total-ordering, or rows sharing a value get skipped/duplicated at page boundaries. Tie-break on a unique column: ORDER BY created_at, id and encode both in the cursor. ⚠ Make cursors opaque (base64 the keyset) so clients can't depend on internals and you can evolve the scheme. Default and cap limit (e.g., default 20, max 100) to protect the backend. Prefer cursor for infinite scroll / large or write-heavy datasets; offset only for small, admin-style, jump-to-page needs.

Filtering, sorting, field selection

  • Filter via query params: ?status=active&min_price=10. Sort with a signed key list: ?sort=-created_at,name (- = desc).
  • Sparse fieldsets / expansion to control payload size: ?fields=id,email and ?expand=customer.
  • Keep filter grammar simple; a full query DSL in query strings is a maintenance trap — reach for GraphQL if clients truly need arbitrary queries.

Error envelope — standardize on RFC 9457 (problem+json)

RFC 9457 (obsoletes 7807), media type application/problem+json. Members: type (URI identifying the problem class), title, status, detail, instance, plus domain extensions.

json
{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Request validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/users",
  "errors": [
    { "field": "email", "code": "invalid_format", "message": "Not a valid email" },
    { "field": "age", "code": "out_of_range", "message": "Must be 18–120" }
  ],
  "request_id": "req_abc123"
}

Rules: machine-readable stable type/code (clients switch on these, never on title/message prose); a request_id for support/tracing; a errors array for per-field validation. Never leak stack traces, SQL, or internal hostnames.

Versioning

StrategyProsCons
URI path /v2/usersexplicit, cache-friendly, easy to route/testversion pinned to URL; coarse-grained
Media type Accept: application/vnd.api.v2+jsonclean URLs, granularharder to test/curl; caches need Vary: Accept
Custom header API-Version: 2clean URLsinvisible in logs/URLs; Vary caution
Query ?version=2trivialpollutes caching/URLs; least recommended
  • Version only for breaking changes. Additive changes (new endpoints, new optional fields, new enum values if clients tolerate unknowns) need no bump — bake "tolerant reader" into client guidance.
  • Breaking = removing/renaming fields, changing types/meaning, changing auth or error format, tightening validation.
  • Deprecate with Deprecation and Sunset response headers (RFC 8594) + Link rel="successor-version"; support N-1 for a published window; publish a migration guide.

GraphQL

  • Don't version — evolve additively; mark removals with @deprecated(reason:). Avoid nullable-to-non-null tightening (breaking).
  • Relay-style connections for lists: edges { node cursor }, pageInfo { hasNextPage endCursor }. Global Node interface + opaque IDs for refetch/caching.
  • Separate input types per mutation (CreateUserInput, UpdateUserInput); mutations return a payload carrying both data and typed errors, not just top-level errors.
  • Nullability is a contract: a non-null field that errors nulls its nearest nullable parent — model expected-failure fields as nullable so one error doesn't blank a whole response.
  • ⚠ N+1 by construction: nested resolvers fan out into per-row fetches. Batch with DataLoader. ⚠ Untrusted clients can craft deep/expensive queries — enforce depth and complexity limits and persisted queries.

gRPC / Protobuf

  • Methods are verbs: GetUser, ListUsers, CreateUser. Package-version namespaces: myapi.v1.
  • Field numbers are the wire contract: never change or reuse a number; reserved deleted numbers/names. Adding fields is backward-compatible; changing a field's type or number is not.
  • Cursor pagination via page_size + page_token / next_page_token (AIP-158). Rich errors via google.rpc.Status + status codes; use canonical codes (NOT_FOUND, ALREADY_EXISTS, FAILED_PRECONDITION, INVALID_ARGUMENT).
  • Use optional (proto3) to distinguish "unset" from zero-value where it matters. Leverage streaming (server/client/bidi) instead of polling.

Examples

REST: paginated collection (OpenAPI 3.1)

yaml
paths:
  /products:
    get:
      summary: List products
      parameters:
        - { name: category, in: query, schema: { type: string } }
        - { name: after, in: query, schema: { type: string }, description: Opaque cursor }
        - { name: limit, in: query, schema: { type: integer, default: 20, maximum: 100 } }
      responses:
        "200":
          description: Cursor-paginated products
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: "#/components/schemas/Product" } }
                  page_info:
                    type: object
                    properties:
                      end_cursor: { type: [string, "null"] }   # 3.1 nullable via type array
                      has_next_page: { type: boolean }
    post:
      summary: Create product
      parameters:
        - { name: Idempotency-Key, in: header, schema: { type: string } }
      responses:
        "201": { description: Created }
        "422": { description: Validation error }

GraphQL: mutation payload + connection

graphql
type Query {
  users(filter: UserFilter, first: Int = 20, after: String): UserConnection!
}
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}
type CreateUserPayload {
  user: User
  errors: [UserError!]!   # typed, in-payload errors
}
type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
}
type UserEdge { node: User!  cursor: String! }

gRPC: list with pagination + reserved fields

protobuf
syntax = "proto3";
package ecommerce.v1;

service ProductService {
  rpc ListProducts(ListProductsRequest) returns (ListProductsResponse);
}
message Product {
  string id = 1;
  string name = 2;
  int64 price_cents = 4;
  reserved 3;            // never reuse a retired field number
  reserved "legacy_sku";
}
message ListProductsRequest {
  string category = 1;
  int32 page_size = 2;   // caps server-side
  string page_token = 3; // opaque cursor
}
message ListProductsResponse {
  repeated Product products = 1;
  string next_page_token = 2;
}

Checklists

Contract design — verify before publishing:

  • [ ] Resources are nouns; casing consistent across path/query/body; nesting ≤2 levels
  • [ ] Every operation's success and error status codes are chosen with 400/401/403/404/409/422/429 used per their semantics
  • [ ] One error envelope (problem+json) with stable machine-readable code/type + request_id, reused everywhere
  • [ ] Pagination shape fixed (cursor for large/write-heavy); cursors opaque; sort key unique/total-ordering with tie-break; limit capped
  • [ ] PATCH semantics declared (merge-patch vs json-patch) via Content-Type
  • [ ] Non-idempotent creates accept Idempotency-Key; optimistic concurrency via ETag/If-Match where lost-update matters
  • [ ] Versioning policy chosen; only breaking changes bump; Deprecation/Sunset headers + migration guide planned

Evolution safety — before shipping a change:

  • [ ] Change classified breaking vs additive; breaking ⇒ new version, not silent
  • [ ] New fields optional; unknown-field tolerance documented for clients
  • [ ] GraphQL: removals @deprecated, not deleted; gRPC: field numbers untouched, retired numbers reserved
  • [ ] No secrets, stack traces, or internal identifiers leak in error bodies
같은 저장소의 Skills

더 많은 Skills

모든 Skills