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.

referencesprovidersaws.md

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

API design — AWS

Service mapping

  • API Gateway (REST API) — full-featured managed REST front: per-method throttling, API keys + usage plans, request validation, WAF, caching. The default for a public REST contract.
  • API Gateway (HTTP API) — leaner, cheaper, lower-latency HTTP front; fewer features (no built-in request validation/caching). Use when you don't need the REST API extras.
  • API Gateway (WebSocket API) — managed WebSocket with $connect/$disconnect routes; AWS holds the connections so you don't size a stateful fleet.
  • AppSync — managed GraphQL (resolvers, real-time subscriptions, auth). Use when the contract is GraphQL and you don't want to run your own server.
  • ALB — L7 routing for gRPC/HTTP to containers/instances when you don't need gateway features; pairs with load-balancing.

When to pick which

REST API for rich public APIs needing keys/throttling/validation; HTTP API for simple low-latency proxies; WebSocket API for managed push; AppSync for GraphQL; ALB for plain gRPC/HTTP service traffic.

Limits / things that bite (verify against current docs)

  • API Gateway has a default ~29s integration timeout — long requests must go async (return 202 + poll, or push). Payloads are capped (~10 MB REST).
  • Account-level and per-method throttle/burst quotas apply; usage plans set per-key rate/burst — design your rate limits to these, not above them.
  • WebSocket API bills per message + connection-minute and caps idle/total connection duration — long-lived clients reconnect.
  • Pricing differs sharply: HTTP API is much cheaper per request than REST API at scale.

Pitfalls

  • Putting a slow synchronous call behind the 29s timeout instead of going async.
  • Assuming API Gateway gives idempotency — it doesn't; you still build the idempotency-key store (DynamoDB with a TTL attribute is the common fit).
  • Reaching for REST API features (and cost) when HTTP API would do.
  • Lock-in: AppSync resolvers and API Gateway mapping templates don't port to other 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