dvcrn API Development
Orchestrate the full API development lifecycle by coordinating design, implementation, testing, and documentation into a single workflow.
When to Use This Skill
- Building a new API from scratch
- Adding endpoints to an existing API
- Redesigning or refactoring an API
- Planning API versioning and migration
- Running a complete API development cycle (design → build → test → document → deploy)
Orchestration Flow
Follow these steps in order. Each step routes to the appropriate skill or tool.
1. Design the API
Load the api-design skill to establish resource models, URL structure, HTTP method semantics, error formats, and pagination strategy.
Deliverables: Resource list, endpoint map, request/response schemas, error format
2. Generate OpenAPI Spec
Produce a machine-readable OpenAPI 3.x specification from the design. Use the OpenAPI template in api-design/assets/openapi-template.yaml as a starting point.
Deliverables: openapi.yaml with all endpoints, schemas, auth schemes, and examples
3. Scaffold Endpoints
Generate route files, request/response types, and validation schemas for each endpoint. Group routes by resource.
Deliverables: Route files, type definitions, validation schemas per resource
4. Implement Business Logic
Write service-layer logic with input validation, authorization checks, database queries, and proper error propagation. Keep controllers thin — business logic lives in the service layer.
Deliverables: Service modules, repository layer, middleware (auth, rate limiting, CORS)
5. Test
Write tests at three levels:
- Unit tests — service logic, validation, error handling
- Integration tests — endpoint behavior with real DB
- Contract tests — response shapes match OpenAPI spec
Deliverables: Test suite with coverage for happy paths, error cases, edge cases, and auth
6. Document
Generate human-readable API documentation with usage examples and SDK snippets. Ensure every endpoint has description, parameters, request/response examples, and error codes.
Deliverables: API docs, changelog, authentication guide
7. Version and Deploy
Apply a versioning strategy, tag the release, update changelogs, and deploy through the pipeline. Follow the api-versioning skill for deprecation and migration guidance.
Deliverables: Version tag, changelog entry, deployment confirmation
API Design Decision Table
Choose the right paradigm for your use case.
| Criteria | REST | GraphQL | gRPC |
|---|---|---|---|
| Best for | CRUD-heavy public APIs | Complex relational data, client-driven queries | Internal microservices, high-throughput |
| Data fetching | Fixed response shape per endpoint | Client specifies exact fields | Strongly typed protobuf messages |
| Over/under-fetching | Common problem | Solved by design | Minimal — schema is explicit |
| Caching | Native HTTP caching (ETags, Cache-Control) | Requires custom caching | No built-in HTTP caching |
| Real-time | Polling or WebSockets | Subscriptions (built-in) | Bidirectional streaming |
| Tooling | Mature — OpenAPI, Postman, curl | Growing — Apollo, Relay, GraphiQL | Mature — protoc, grpcurl, Buf |
| Learning curve | Low | Medium | Medium-High |
| Versioning | URL or header versioning | Schema evolution with @deprecated |
Package versioning in .proto |
Rule of thumb: Default to REST for public APIs. Use GraphQL when clients need flexible queries across related data. Use gRPC for internal service-to-service communication.
API Checklist
Run through this checklist before marking any API work as complete.
Authentication & Authorization
- Authentication mechanism chosen (JWT, OAuth2, API key)
- Authorization rules enforced at every endpoint
- Tokens validated and scoped correctly
- Secrets stored securely (never in code or logs)
Rate Limiting
- Rate limits configured per endpoint or consumer tier
-
RateLimit-*headers included in responses -
429 Too Many Requestsreturned withRetry-Afterheader - Rate limit strategy documented for consumers
Pagination
- All collection endpoints paginated
- Pagination style chosen (cursor-based or offset-based)
-
page_sizebounded with a sensible maximum - Total count or
hasNextPageindicator included
Filtering & Sorting
- Filter parameters validated and sanitized
- Sort fields allow-listed (no arbitrary column sorting)
- Default sort order defined and documented
Error Handling
- Consistent error response schema across all endpoints
- Correct HTTP status codes (4xx for client, 5xx for server)
- Validation errors return field-level detail
- Internal errors never leak stack traces or sensitive data
Versioning
- Versioning strategy selected and applied uniformly
- Breaking vs non-breaking change policy documented
- Deprecation timeline communicated via
Sunsetheader
CORS
- Allowed origins configured (no wildcard
*in production with credentials) - Allowed methods and headers explicitly listed
- Preflight (
OPTIONS) requests handled correctly
Documentation
- OpenAPI / Swagger spec generated and up to date
- Every endpoint has description, parameters, and example responses
- Authentication requirements documented
- Error codes and meanings listed
- Changelog maintained for each version
Security
- Input validation on all fields
- SQL injection prevention
- HTTPS enforced
- Sensitive data never in URLs or logs
- CORS configured correctly
Monitoring
- Structured logging with request IDs
- Error tracking configured (Sentry, Datadog, etc.)
- Performance metrics collected (latency, error rate)
- Health check endpoint available (
/health) - Alerts configured for error rate spikes
Skill Routing Table
| Need | Skill | Purpose |
|---|---|---|
| API design principles | api-design |
Resource modeling, HTTP semantics, pagination, error formats |
| Versioning strategy | api-versioning |
Version lifecycle, deprecation, migration patterns |
| Authentication | auth-patterns |
JWT, OAuth2, sessions, RBAC, MFA |
| Error handling | error-handling |
Error types, retry patterns, circuit breakers, HTTP errors |
| Rate limiting | rate-limiting |
Algorithms, HTTP headers, tiered limits, distributed limiting |
| Caching | caching |
Cache strategies, HTTP caching, invalidation, Redis patterns |
| Database migrations | database-migrations |
Schema evolution, zero-downtime patterns, rollback strategies |
NEVER Do
- NEVER skip the design phase — jumping straight to code produces inconsistent APIs that are expensive to fix
- NEVER expose database schema directly — API resources are not database tables; design around consumer use cases
- NEVER ship without authentication — every production endpoint must have an auth strategy
- NEVER return inconsistent error formats — every error response must follow the same schema
- NEVER break a published API without a versioning plan — breaking changes require a new version, migration guide, and deprecation timeline
- NEVER deploy without tests and documentation — untested APIs ship bugs, undocumented APIs frustrate developers