API Contract Design: REST, GraphQL, OpenAPI
Turns product requirements into a REST or GraphQL API contract: resources, errors, pagination, versioning, and an OpenAPI 3.1 spec.
Before & after
Same prompt, same agent — the only difference is the skill.
That's a complex API with lots of moving parts. Before I sketch endpoints, I'd need to know: Who's your primary user? How many uploads per day are you expecting? Do you need real-time notifications? Will you have complex permissions (followers, private albums)? What's your data model for photos, comments, likes? Once we nail those, I can design the endpoints and versioning strategy.
REST API DESIGN: SocialPhoto v1
RESOURCE ENDPOINTS
Users
GET /api/v1/users/{id} → User profile (name, avatar, follower count)
PATCH /api/v1/users/{id} → Update profile
DELETE /api/v1/users/{id} → Deactivate account
Photos
POST /api/v1/photos → Upload (multipart/form-data, 5MB max)
GET /api/v1/photos/{id} → Fetch with comments count
PATCH /api/v1/photos/{id} → Update caption or visibility
DELETE /api/v1/photos/{id} → Soft delete
GET /api/v1/photos?user_id={id}&limit=20&offset=0 → Paginated feed
Comments
POST /api/v1/photos/{id}/comments → Add comment
GET /api/v1/photos/{id}/comments?limit=10 → Paginated
DELETE /api/v1/comments/{id} → Remove comment
Likes
POST /api/v1/photos/{id}/like → Toggle like (idempotent)
GET /api/v1/photos/{id}/likes?limit=50 → Liker list
ERROR HANDLING
• 400 Bad Request (invalid JSON, missing field)
• 401 Unauthorized (expired token)
• 403 Forbidden (not owner of resource)
• 404 Not Found (resource doesn't exist)
• 429 Too Many Requests (rate limited at 100 req/min)
• 500 Internal Server Error (DB down)
VERSIONING: URL-based (/v1/, /v2/) for clarity
AUTHENTICATION: Bearer JWT in Authorization header
PAGINATION: Cursor-based (offset + limit pattern above)
RATING: 200 photos/user/day soft limitAbout this skill
Your endpoints were added one at a time, and it shows. Errors come back in three shapes. Pagination breaks when rows are inserted mid-scroll. A retried POST creates duplicate orders. Nobody can say whether renaming a field is safe to ship. This skill designs the API contract before any code exists, or audits the one you already have, so clients can build against it without surprises.
What it does
- Models resources from the product's nouns and state transitions, not your database tables, and makes side-effecting transitions explicit actions
- Defines one error envelope (RFC 9457 problem details) with stable machine-readable codes and a status-code catalog covering 400/422, 401/403/404, 409/412, and 429
- Specifies cursor pagination with stable sort tiebreakers, plus idempotency keys for POST and ETag/If-Match for concurrent edits
- Classifies proposed changes as additive, soft-breaking, or breaking, and writes a versioning and deprecation policy
- Writes OpenAPI 3.1 YAML with reusable components and realistic examples, or a GraphQL SDL with connections and typed mutation payloads
- Reviews pasted specs and flags inconsistencies, leaky IDs, float money, and missing error cases, ordered by severity
What you get
A design summary with stated assumptions, an endpoint table, shared conventions, and a spec you can paste into your docs or codegen. When you send an existing API, you get a prioritized review with concrete fixes instead.
Best for
Backend and full-stack engineers starting a new service or public API, tech leads standardizing APIs across teams, and anyone about to ship a change who needs to know whether it breaks clients.
SKILL.md preview
---
name: api-contract-design
description: Designs REST or GraphQL API contracts from product requirements. Covers the resource model, endpoint table, RFC 9457 error envelope, cursor pagination, idempotency, concurrency control, versioning and deprecation policy, and an OpenAPI 3.1 spec with real examples. Also reviews existing specs for breaking changes and inconsistencies. Use when the user says "design an API for...", "write the OpenAPI spec for these endpoints", "review my API design", "how should I version this API", "is this a breaking change", "my endpoints are all inconsistent", "clients keep double-creating orders when they retry", or "REST or GraphQL for this?"
---
… (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.