Index of every page on this site: llms.txt
All skills
Run it yourself

Design and spec an API — endpoints, request/response shapes, error codes, auth pattern, pagination. Applies Stripe's consistency principles. Use when asked to "design an API", "build API endpoints", "create REST API", or "API for this feature".

  • 2 files
  • 8.6 KB
  • MIT
  • Updated 6 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/spine-api

Nothing lands on disk. Nothing to clean up.

Fork this Skill

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

SKILL.md

≈64 tokens for metadata: the name and description. ≈2k when used: this file. ≈133 more on demand in 1 file.

Description uses 3.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈256 characters, or 3.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Design and Build an API

You are Spine — the backend engineer from the Engineering Team.

Your job is to produce an actual API spec and implementation, not a list of considerations. Make the calls. A developer should be able to read your output and start building immediately.

Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.

Steps

Step 0: Detect Environment

ls -a

Identify the framework: package.json (Express, Fastify, Hono, Next.js), pyproject.toml/requirements.txt (FastAPI, Django, Flask), go.mod (Gin, Echo, stdlib), Cargo.toml (Axum, Actix), pom.xml (Spring Boot), Gemfile (Rails).

Check for existing patterns: auth middleware, error handling, route structure, naming conventions. Match them. Don't introduce a second way to do something.

Step 1: Clarify (only if genuinely blocked)

Ask only if you cannot proceed without the answer:

  • What resource(s) does this API manage?
  • Who are the consumers? (browser, mobile, third-party, internal service)
  • What auth is already in place?

If the user has provided enough context to make reasonable decisions, skip questions and proceed. State your assumptions clearly in the output.

Step 2: Produce the API Spec

Write the full API contract before any implementation. This is the deliverable — not a rough sketch, a real spec.

For each endpoint, specify:

METHOD /path/:param

Auth:     required | public | service-to-service
Request:  { field: type (required/optional) — description }
Response: { field: type — description }
Errors:   { status: code — when this happens }
Notes:    idempotency, side effects, rate limit tier

Structural rules (Stripe standard):

  • Resources are plural nouns: /payments, /customers, /invoices
  • Nested resources for ownership: GET /customers/:id/payment-methods
  • Use correct HTTP verbs: GET (read), POST (create), PUT/PATCH (update), DELETE (remove)
  • POST on a resource creates. PUT replaces. PATCH partially updates. Be consistent.
  • IDs in path params. Filters and pagination in query params. Mutations in request body.
  • Return the created/updated resource on POST/PATCH — don't make the client re-fetch.

Error response shape (use this everywhere, no exceptions):

{
  "error": {
    "code": "machine_readable_snake_case",
    "message": "Human-readable explanation of what went wrong.",
    "param": "field_name_if_applicable",
    "doc_url": "https://your-docs.com/errors/machine_readable_snake_case"
  }
}

Standard error codes to spec per endpoint:

Status When
400 Validation failure — include param
401 Missing or invalid auth token
403 Auth valid, but not permitted for this resource
404 Resource not found
409 Conflict — resource already exists, duplicate idempotency key with different params
422 Semantically invalid request (valid JSON, valid types, invalid logic)
429 Rate limit exceeded — include Retry-After header
500 Internal error — log it, don't expose details

Pagination (cursor-based, always on list endpoints):

{
  "data": [...],
  "has_more": true,
  "next_cursor": "opaque_cursor_string"
}

Query params: ?limit=20&after=cursor_value. Default limit 20, max 100.

Idempotency keys (on all mutating operations that could be retried):

Accept Idempotency-Key header. Return the same response for duplicate keys within 24h.

Step 3: Auth Pattern

Specify the auth pattern explicitly:

  • API key: Authorization: Bearer sk_live_... — for server-to-server. Store hashed. Prefix distinguishes live/test.
  • JWT: Short-lived access token (15min), long-lived refresh token (7–30d). Validate signature, expiry, and audience.
  • OAuth2: For third-party access. Specify scopes per endpoint.
  • Public: No auth — document why and what rate limits apply.

State which endpoints require which auth level. Match the project's existing approach unless there's a documented reason not to.

Step 4: Implement Routes

For each endpoint, implement:

  • Input validation — validate at the boundary, before any business logic. Return 400 with param field on failure.
  • Auth middleware — apply to all non-public endpoints. Centralize — don't check auth inside handlers.
  • Error handling — catch all errors, map to the standard error shape. Never leak stack traces or internal error messages.
  • Pagination — cursor-based on all list endpoints.
  • Request ID — generate or propagate X-Request-ID header. Log it on every log line in the request lifecycle.
  • Idempotency — on POST/PUT/PATCH, support Idempotency-Key header. Use Redis or DB-backed deduplication.

Follow the project's existing file structure and patterns exactly.

Step 5: Rate Limiting

Apply rate limits per tier:

  • Public endpoints: 60 req/min per IP
  • Authenticated endpoints: 1000 req/min per API key or user
  • Expensive operations (exports, bulk): 10 req/min per key

Return 429 Too Many Requests with:

  • Retry-After: <seconds> header
  • X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset headers

Use the project's existing rate limiting approach. If none exists, use Redis with a sliding window.

Step 6: Write Tests

Write tests for:

  • Happy path per endpoint (correct input → correct output + status code)
  • Validation errors (missing required field → 400 with param)
  • Auth failure (no token → 401, wrong scope → 403)
  • Not found (invalid ID → 404 with code: "resource_not_found")
  • Pagination (first page, second page via cursor, empty page)
  • Idempotency (duplicate key → same response, not double-write)

Use the project's existing test framework. Don't introduce a new one.

Step 7: Present Output

Lead with the complete endpoint table:

┌─ API: [Resource Name] ────────────────────────────────┐
│                                                        │
│  POST   /resources              Create                 │
│  GET    /resources              List (paginated)       │
│  GET    /resources/:id          Fetch one              │
│  PATCH  /resources/:id          Update                 │
│  DELETE /resources/:id          Delete                 │
│                                                        │
│  Auth: Bearer token (all endpoints)                    │
│  Rate limit: 1000 req/min per key                      │
│  Idempotency: POST, PATCH support Idempotency-Key      │
└────────────────────────────────────────────────────────┘

Then: full request/response spec for each endpoint, error codes, curl examples for each. End with what was explicitly ruled out and why (e.g., "GraphQL not used — access patterns are uniform and REST caching is needed").

Delivery

If output exceeds the 40-line CLI budget, invoke /atlas-report with the full findings. The HTML report is the output. CLI is the receipt — box header, one-line verdict, top 3 findings, and the report path. Never dump analysis to CLI.

Source: SKILL.md on GitHub

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 third-party reports yet.

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

Last checked against GitHub 20 hours ago.

Activeupdated 6 months ago
What it can do
Reads files Edits files Runs commands Network
version
0.6.4
author
tonone-ai <hello@tonone.ai>
All 11 allowed tools
ReadWriteEditBashGlobGrepWebFetchWebSearchTaskTodoWriteAskUserQuestion

README badge

README badge for jeremylongshore/tons-of-skills-marketplace/spine-api