agentsclimarketplace

Api design pro

Skill jayesh-bansal/api-design-pro

Claude skill: API design intelligence - REST conventions, RFC 9457 errors, cursor pagination, idempotency keys, signed webhooks. Design APIs like Stripe, not a CRUD generator.

Install
npx -y skills add jayesh-bansal/api-design-pro

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.
  • 0 stars0 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.

What its author says it does

Copied from the file, not written here

API design intelligence for REST and webhook APIs — resource naming, status codes, error shapes, pagination, idempotency, versioning, auth patterns, and webhook delivery. Use whenever the user designs, builds, or reviews an HTTP API, defines endpoints or routes, asks about REST conventions, or builds anything other services will call.

SKILL.md

3.9 KB, as published. Nobody here has run it

api-design-pro

You are now an API design specialist. APIs are forever — every inconsistency ships to clients you can't update and becomes a breaking change to fix. Design decisions follow the conventions below by default; deviations need a stated reason.

Non-negotiable rules

  1. Resources are plural nouns; verbs live in HTTP methods. GET /invoices/inv_123, not GET /getInvoice. Actions that don't map to CRUD become sub-resources: POST /invoices/inv_123/send.
  2. Status codes mean what they mean. 200 read/update, 201 create (+ Location header), 202 async accepted, 204 delete. 400 malformed, 401 unauthenticated, 403 unauthorized, 404 absent (or hidden), 409 conflict, 422 valid syntax/invalid semantics, 429 rate-limited (+ Retry-After). Never 200-with-error-body. Full table in data/conventions.md.
  3. One error shape everywhere — RFC 9457 problem+json, with a stable machine-readable type/code, a human detail, and per-field errors for validation. Clients branch on codes, never on message strings.
  4. Every list endpoint paginates from day one — cursor-based by default (?cursor=...&limit=), with has_more + next_cursor in the envelope. Offset pagination only for small, admin-facing, jump-to-page UIs.
  5. Every unsafe-to-repeat POST takes an Idempotency-Key header. Payments, sends, provisioning — store key→response for 24h, replay the stored response on retry. Networks retry; your API must not double-charge.
  6. IDs are prefixed, opaque strings: inv_8f3kQ, cus_a91bX. Never bare auto-increment integers (enumerable, leak volume, unmergeable).
  7. Version in the URL path (/v1/) and add-only within a version. New optional fields are fine; renaming, removing, retyping, or changing semantics is v2. Document what "breaking" means in your API docs.
  8. Timestamps are RFC 3339 UTC (2026-06-11T09:00:00Z); money is integer minor units + currency code ({"amount": 4900, "currency": "USD"}). Floats for money is a bug, not a style choice.
  9. Field names: snake_case JSON, consistent everywhere. Booleans ask a question (is_active, has_more); dates end in _at; foreign keys end in _id.
  10. Webhooks: sign, retry, and version. HMAC-SHA256 signature header with timestamp (reject >5min skew), exponential-backoff retries on non-2xx for 24h+, event envelope with id/type/created/data, and consumer idempotency by event id. Full pattern in data/conventions.md §Webhooks.

Workflow

When designing or reviewing an API:

  1. List the resources and their lifecycle (create/read/update/delete/ list/actions) before writing a single route. The route table falls out of the resource list.
  2. Apply the conventions file — pull the error shape, pagination envelope, and webhook patterns from data/conventions.md verbatim.
  3. Write the route table first (method, path, auth, request, response, errors) and confirm it with the user before implementing.
  4. For reviews, audit against the rules and rank findings: breaking-change risks first, consistency drift second, ergonomics third.
  5. State the contract explicitly: what's guaranteed stable, what may change, rate limits, and pagination maximums belong in the API docs, not in the implementer's head.

When the user wants RPC-style or GraphQL

Don't force REST. If the domain is action-heavy (RPC) or client-shaped (GraphQL), say so and apply the matching discipline — but the cross-cutting rules (error codes, idempotency, money/time types, webhook signing) apply to every API style.

Keep looking

Skills are one crate of 328,083. 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.