agentsclimarketplace

Api design

Skill bjornjee/skills/skills/api-design

Use when designing or reviewing an HTTP/RPC API surface — resource modeling, pagination, error envelopes, versioning, idempotency. Falsifiable contracts, not style preferences.From its SKILL.md

Install
npx -y skills add bjornjee/skills --skill api-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
  • 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.1 KB, as published. Nobody here has run it

API Design

Rules for any API another team, service, or future-you will call. Every rule here is checkable in review.

Resources

  • Nouns, not verbs: POST /orders, not POST /createOrder. Verbs allowed only for true actions with no resource representation (POST /orders/{id}/cancel).
  • One resource, one canonical URL. Aliases and "convenience" routes multiply cache keys and auth checks.
  • Nested paths max two levels (/orders/{id}/items). Deeper nesting means the child deserves a top-level resource.

Pagination

  • Cursor-based for any dataset that mutates or can exceed ~10k rows. Offset pagination on mutable data skips/duplicates rows mid-scroll — that is a bug, not a style choice.
  • Offset is acceptable for small, effectively-immutable datasets (admin lists, lookups).
  • The cursor is opaque to clients (base64 of sort key + id). Documenting its internals turns it into API surface.
  • Every list response carries next_cursor (null = end). No "call until empty page" contracts.

Errors

  • One error envelope repo-wide, RFC 7807 shape: { "type", "title", "status", "detail", "instance" }. A second error shape anywhere is a BLOCK in review.
  • Machine-readable type (stable URI/slug), human-readable detail. Clients branch on type, never parse detail.
  • 404 vs 403 leak rule: if the caller may not know the resource exists, return 404 for both missing and forbidden. Returning 403 confirms existence.
  • Validation failures: 422 with a per-field errors array inside the envelope, not the first error only.

Versioning

  • Additive-only within a major version: new optional fields and new endpoints are safe; renaming, retyping, or removing anything is breaking.
  • Breaking change ⇒ new major path (/v2/) + deprecation window on v1 with a Sunset header and a dated removal plan. No silent behavior changes.
  • Never version individual fields or negotiate versions via optional headers — one axis of versioning only.

Idempotency & semantics

  • Every non-GET mutation a client may retry (payments, order creation, webhooks) requires an Idempotency-Key header; same key + same body replays the stored result, same key + different body returns 409.
  • PUT is full replace, PATCH is partial. In PATCH, absent field = unchanged, null = clear. Document it once, follow it everywhere (omission-preserves-stale-state bugs live here).
  • GET/HEAD never mutate. No "GET with side effects" even for convenience.

Conventions

  • Timestamps: UTC, ISO-8601 with offset (2026-07-05T10:00:00Z). Epoch integers only in high-volume telemetry.
  • IDs in responses are strings, even when numeric today — retyping later is a breaking change.
  • Field naming picks one case (snake_case JSON) and never mixes.

When NOT to apply

Internal one-consumer endpoints you can change atomically with the caller can skip versioning ceremony and idempotency keys — say so in the handler comment. The error envelope and 404/403 rules still apply.

Keep looking

Skills are one crate of 609,689. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.