Index of every page on this site: llms.txt
All skills
proyecto26 avatar

/api-design

@228d57d
Run it yourself

This skill should be used when the user needs to "design the API", do "endpoint design", pin down a "request/response shape", choose a "pagination" strategy (cursor vs offset), add an "idempotency key" to a write, plan "API versioning", an "error contract", or pick between "REST vs gRPC vs GraphQL" or "WebSocket vs polling". Use it whenever a design has reached the interface — the concrete request, response, primary access path, and how clients page, retry, and version — even if the user only said "the boxes talk to each other".

Use this Skill: https://skilld.dev/gh/proyecto26/system-design-skills/api-design

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesprovidersgeneric.md

≈594 tokens on demand. Your agent reads this file only when SKILL.md points to it.

API design — generic / self-hosted

The vendor-neutral default. When no cloud is named, this is the answer.

What to run

  • REST/JSON over an HTTP framework + a reverse proxy / API gateway you run (NGINX, Envoy, Kong, Traefik) for routing, TLS termination, auth, and rate limiting at the edge.
  • gRPC with protobuf for internal service-to-service calls; add Envoy or grpc-web as a gateway when browsers must reach it.
  • GraphQL via a server library (Apollo, graphql-js, gqlgen) — put depth/cost limits and persisted-query allowlists in front of it.
  • WebSocket/SSE terminated at the app or a connection-aware proxy; SSE rides plain HTTP, WebSocket needs proxy support for the Upgrade handshake.
  • OpenAPI (REST) / protobuf (gRPC) as the schema source of truth — generate clients, server stubs, and docs from it so the contract can't drift.

Topology

  • Edge gateway/proxy → service. The gateway owns cross-cutting concerns (auth, rate limiting, TLS, request size caps) so each service doesn't re-implement them.
  • Idempotency-key store: a fast, durable KV (e.g. Redis with persistence, or a DB table) holding key → response with a TTL; co-locate with or transact alongside the write it protects.

Limits / things that bite

  • A stateless HTTP gateway scales horizontally; a WebSocket/SSE tier does not — it holds a connection (and memory) per client, so sizing is connections, not QPS, and load balancing must be connection-aware (sticky or a shared session store).
  • Default request body and header size caps in the proxy will silently reject large payloads — set them deliberately.
  • Self-managed rate limiting and idempotency dedupe need a shared store to work across instances (an in-process counter doesn't; → resilience-failure).

Pitfalls

  • No managed quota/throttle layer — you build and operate it (the gateway helps but you configure the limits and the storage behind them).
  • Forgetting connection draining on deploy → WebSocket clients all reconnect at once (reconnect storm; add jitter).
  • Hand-written clients drift from the server shape — generate from OpenAPI/protobuf instead.

Operationally heavier than a managed gateway, but zero lock-in and full control of versioning, auth, and limits. Use when running your own infra or for portability across clouds.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts24d3 checks · Risk SAFE
  • Gen Agent Trust Hub24d

    The skill provides architectural guidance and best practices for designing APIs, covering protocols, pagination, and idempotency. No security issues were detected.

  • Socket24d

    No alerts

  • Snyk24d

    Risk: LOW · No issues

Signed by skilld at 228d57d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 weeks ago.

Activeupdated 4 weeks ago

README badge

README badge for proyecto26/system-design-skills/api-design