Api Design Principles
Run a structured REST API design review before implementation so endpoints, pagination, and errors stay consistent.
Overview
api-design-principles is an agent skill most often used in Build (also Ship review) that applies a pre-implementation REST API design checklist before you code endpoints.
Install
npx skills add https://github.com/wshobson/agents --skill api-design-principlesWhat is this skill?
- Pre-implementation checklist across resources, HTTP methods, and status codes
- Pagination, filtering, sorting, and sparse fieldsets expectations
- Auth, rate limiting, and error-shape guidance (401/403/422/429)
- Versioning strategy gate before endpoints ship
- Collection endpoint patterns with default and max page sizes
Adoption & trust: 22.1k installs on skills.sh; 36.5k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are about to implement an API without a shared checklist, so naming, pagination, and error semantics will diverge under pressure.
Who is it for?
Solo builders designing a new HTTP API or tightening an existing public surface before coding or documenting it.
Skip if: GraphQL-only designs, gRPC-first services, or teams that already enforce an org-wide OpenAPI standard with automated lint in CI.
When should I use this skill?
Starting a new API or revising public endpoints before implementation or client integration.
What do I get? / Deliverables
You leave the review with explicit decisions on resources, HTTP methods, status codes, pagination, filtering, and versioning ready for implementation or OpenAPI.
- Completed pre-implementation API design checklist
- Documented pagination, versioning, and error-handling conventions
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Primary shelf is Build/backend because the checklist governs how you shape resources and HTTP contracts before coding the API surface. Backend subphase is where resource naming, verbs, status codes, and versioning decisions are locked in pre-implementation.
Where it fits
Confirm MVP API surface and pagination defaults before promising integrations to early users.
Walk the checklist before scaffolding CRUD routes and auth middleware.
Verify status codes and versioning before tagging a v1 public release.
How it compares
A human-review checklist for API shape—not an OpenAPI generator or runtime SDK.
Common Questions / FAQ
Who is api-design-principles for?
Indie backend builders and small teams defining REST-style HTTP APIs who want a consistent pre-coding review.
When should I use api-design-principles?
In Build when shaping backend endpoints; in Ship during review before merge or launch; in Validate when scoping an API-first MVP contract.
Is api-design-principles safe to install?
It is documentation-style guidance with no special tool permissions; still review the Security Audits panel on this page like any third-party skill.
SKILL.md
READMESKILL.md - Api Design Principles
# API Design Checklist ## Pre-Implementation Review ### Resource Design - [ ] Resources are nouns, not verbs - [ ] Plural names for collections - [ ] Consistent naming across all endpoints - [ ] Clear resource hierarchy (avoid deep nesting >2 levels) - [ ] All CRUD operations properly mapped to HTTP methods ### HTTP Methods - [ ] GET for retrieval (safe, idempotent) - [ ] POST for creation - [ ] PUT for full replacement (idempotent) - [ ] PATCH for partial updates - [ ] DELETE for removal (idempotent) ### Status Codes - [ ] 200 OK for successful GET/PATCH/PUT - [ ] 201 Created for POST - [ ] 204 No Content for DELETE - [ ] 400 Bad Request for malformed requests - [ ] 401 Unauthorized for missing auth - [ ] 403 Forbidden for insufficient permissions - [ ] 404 Not Found for missing resources - [ ] 422 Unprocessable Entity for validation errors - [ ] 429 Too Many Requests for rate limiting - [ ] 500 Internal Server Error for server issues ### Pagination - [ ] All collection endpoints paginated - [ ] Default page size defined (e.g., 20) - [ ] Maximum page size enforced (e.g., 100) - [ ] Pagination metadata included (total, pages, etc.) - [ ] Cursor-based or offset-based pattern chosen ### Filtering & Sorting - [ ] Query parameters for filtering - [ ] Sort parameter supported - [ ] Search parameter for full-text search - [ ] Field selection supported (sparse fieldsets) ### Versioning - [ ] Versioning strategy defined (URL/header/query) - [ ] Version included in all endpoints - [ ] Deprecation policy documented ### Error Handling - [ ] Consistent error response format - [ ] Detailed error messages - [ ] Field-level validation errors - [ ] Error codes for client handling - [ ] Timestamps in error responses ### Authentication & Authorization - [ ] Authentication method defined (Bearer token, API key) - [ ] Authorization checks on all endpoints - [ ] 401 vs 403 used correctly - [ ] Token expiration handled ### Rate Limiting - [ ] Rate limits defined per endpoint/user - [ ] Rate limit headers included - [ ] 429 status code for exceeded limits - [ ] Retry-After header provided ### Documentation - [ ] OpenAPI/Swagger spec generated - [ ] All endpoints documented - [ ] Request/response examples provided - [ ] Error responses documented - [ ] Authentication flow documented ### Testing - [ ] Unit tests for business logic - [ ] Integration tests for endpoints - [ ] Error scenarios tested - [ ] Edge cases covered - [ ] Performance tests for heavy endpoints ### Security - [ ] Input validation on all fields - [ ] SQL injection prevention - [ ] XSS prevention - [ ] CORS configured correctly - [ ] HTTPS enforced - [ ] Sensitive data not in URLs - [ ] No secrets in responses ### Performance - [ ] Database queries optimized - [ ] N+1 queries prevented - [ ] Caching strategy defined - [ ] Cache headers set appropriately - [ ] Large responses paginated ### Monitoring - [ ] Logging implemented - [ ] Error tracking configured - [ ] Performance metrics collected - [ ] Health check endpoint available - [ ] Alerts configured for errors ## GraphQL-Specific Checks ### Schema Design - [ ] Schema-first approach used - [ ] Types properly defined - [ ] Non-null vs nullable decided - [ ] Interfaces/unions used appropriately - [ ] Custom scalars defined ### Queries - [ ] Query depth limiting - [ ] Query complexity analysis - [ ] DataLoaders prevent N+1 - [ ] Pagination pattern chosen (Relay/offset) ### Mutations - [ ] Input types defined - [ ] Payload types with errors - [ ] Optimistic response support - [ ] Idempotency considered ### Performance - [ ] DataLoader for all relationships - [ ] Query batching enabled - [ ] Persisted queries considered - [ ] Response caching implemented ### Documentation - [ ] All fields documented - [ ] Deprecations marked - [ ] Examples provided - [ ] Schema introspection enabled """ Production-ready REST API template using FastAPI. Includes pagination, filtering, error handling, and best pra