REST Endpoint Contract Design and Consistency
Designs REST endpoints that match your existing API: routes, status codes, errors, pagination, idempotency, and safe evolution.
Before & after
Same prompt, same agent — the only difference is the skill.
I can definitely help you design a solid API for your SaaS product. REST is generally a good architectural choice for most APIs, although you might want to also consider GraphQL depending on your specific client needs and query patterns. You'll need to think through your resource structure carefully, choose an authentication method, decide on your error handling approach, and implement pagination properly. Different companies and teams have different API design conventions and standards. What specific business resources do you need API endpoints for—users, accounts, transactions, that kind of thing?
REST API SPECIFICATION — CONSISTENT CONVENTIONS:
BASE URL: https://api.example.com/v1/
RESOURCES: /users, /projects, /tasks, /comments
ROUTE PATTERNS (consistent across all resources):
GET /projects → List projects. Returns paginated 20 results per page.
GET /projects/:id → Get single project by ID.
POST /projects → Create project. Request body required.
PUT /projects/:id → Replace entire project (all fields required).
PATCH /projects/:id → Partial update (only changed fields).
DELETE /projects/:id → Delete project. Returns 204 No Content.
HTTP STATUS CODES (consistent):
200 OK — Request succeeded. Data returned.
201 Created — Resource created. Location header points to new resource URI.
204 No Content — Successful deletion. No body.
400 Bad Request — Invalid input (missing field, wrong type). Error body: {error: 'Invalid email format', field: 'email'}.
401 Unauthorized — Missing or invalid auth token.
404 Not Found — Resource doesn't exist.
422 Unprocessable Entity — Request valid but business logic failed (e.g., duplicate email).
500 Internal Server Error — Server fault (logged).
RESPONSE STRUCTURE (JSON):
Success: {data: {...}, meta: {created_at: '2026-07-31T10:00:00Z'}}
Error: {error: 'string', status_code: int, request_id: 'uuid'}
PAGINATION:
Query params: ?page=1&per_page=20. Defaults: page=1, per_page=20.
Response includes: {data: [...], meta: {page: 1, per_page: 20, total_count: 1450, total_pages: 73}}
AUTHENTICATION: Bearer token (JWT). Header: Authorization: Bearer <token>. Token expiry: 7 days. Refresh endpoint: POST /auth/refresh.
VERSIONING: Path-based (/v1/, /v2/). Old major version supported 12+ months after new release. Announce deprecation 6 months before removal.About this skill
Claude can produce endpoints that look fine one at a time and still drift as a set. You get /archiveOrder next to /orders, camelCase in a snake_case API, 200 responses with an error inside, offset pagination that skips rows, and a "small" field rename that breaks every mobile client. This skill reads the conventions your API already uses, designs new endpoints to match them, and flags each decision that is hard to undo once clients depend on it.
What it does
- Infers your casing, envelope, error shape, ID format, and pagination style from pasted routes or code, and keeps new endpoints consistent with them
- Models non-CRUD actions (archive, cancel, refund, approve) correctly, choosing between a field update, an action sub-resource, and a created resource based on side effects
- Picks precise status codes (201 with Location, 202 for async work, 409 vs 412 vs 422, 404 vs 403 for other tenants' data)
- Designs RFC 9457 style error bodies with stable machine codes and field-level details
- Adds cursor pagination with stable sort keys, Idempotency-Key handling for side-effecting POSTs, and ETag/If-Match for contested updates
- Classifies every proposed change as additive or breaking, and gives a migration path for the breaking ones
What you get
An endpoint contract with a route table, example requests and responses, an error table, and a short list of decisions with the reason for each. Pasted designs get a review listing concrete fixes.
Best for
Backend engineers and tech leads who are adding endpoints to a live API, reviewing an API PR, or standardizing several services that grew inconsistent.
SKILL.md preview
---
name: rest-endpoint-contract-design
description: Designs and reviews REST endpoint contracts (routes, methods, status codes, error bodies, pagination, idempotency, concurrency, versioning) so they match the API's existing conventions and can evolve without breaking clients. Use when the user says "add an endpoint for X", "design the API for this feature", "review these routes", "what status code should this return", "how do I model archive/cancel/approve in REST", "is this a breaking change", or "our API is inconsistent and every endpoint returns errors differently".
---
# REST Endpoint Contract Design and Consistency
… (sign up to view the full skill)More development skills
View all Development skills →Production Go: Concurrency, Services & Profiling
Production Go code with leak-free goroutines, context-correct services, wrapped errors, and pprof-driven performance fixes.
Backend Feature Build Plan
Builds one backend feature through gates: confirmed requirements, one-screen design, small tested slices, and a deploy/rollback handoff.
Consistent, Safe Application Logging
Adds structured, correlated logs with useful severity, safe fields, bounded volume, and targeted verification.
Reliable WebSocket Messaging and Scaling
Build WebSocket and Socket.IO systems with authorized rooms, reconnect recovery, bounded queues, and multi-node presence.