API Design Template for Product Teams
API design is product design for developers. An API is a product with its own users (developers), its own UX (endpoint design, error messages, documentation), and its own success metrics (adoption, time-to-first-call, error rates). PMs working on platforms or integrations need to understand API design.
This template covers the API design decisions that PMs should drive or at least be involved in, not the implementation details that engineers own.
Template sections
6 sections covering the complete api design workflow.
API Overview and Use Cases
Define the primary use cases the API enables. Who will use it (internal teams, partners, third-party developers)? What will they build with it? What is the expected call volume? These decisions affect every subsequent design choice: authentication, rate limits, pricing, and documentation investment.
Resource Design
Define the resources (nouns) and actions (verbs) the API exposes. Use RESTful conventions: GET for reading, POST for creating, PATCH for updating, DELETE for removing. Design resources around user concepts, not database tables. Example: /projects/:id/requirements is better than /requirement_rows?project_id=X.
Authentication and Authorization
Define the auth model: API keys (simple, for server-to-server), OAuth 2.0 (for user-context access), or JWT tokens (for session-based access). Document the scopes: what permissions does each scope grant? Define rate limits per authentication level (free, paid, partner).
Versioning Strategy
Define the versioning approach: URL path versioning (/v1/, /v2/), header versioning, or query parameter versioning. Define the deprecation policy: how much notice before removing an API version, what migration support is provided, and how breaking changes are communicated.
Error Handling
Define the error response format: consistent structure with error code, message, and details. Use standard HTTP status codes correctly: 400 for client errors, 401 for authentication, 403 for authorization, 404 for not found, 429 for rate limiting, 500 for server errors. Good error messages tell the developer what to fix.
Developer Experience
Define the developer experience investment: documentation (auto-generated from OpenAPI spec or hand-written), SDKs (which languages), sandbox environment, quickstart guides, and code examples. The developer experience determines API adoption as much as the API design itself.
Copy-paste template
# API Design: [API Name]
## Overview
- **Audience:** [Internal / Partners / Public]
- **Primary use cases:** [List]
- **Expected volume:** [Calls per day]
## Resources
| Resource | Endpoints | Description |
|---|---|---|
| /api/v1/[resource] | GET, POST | [Description] |
| /api/v1/[resource]/:id | GET, PATCH, DELETE | [Description] |
## Authentication
- **Method:** [API Key / OAuth 2.0 / JWT]
- **Scopes:** [List]
- **Rate limits:** [Per tier]
## Versioning
- **Strategy:** URL path (/v1/)
- **Deprecation notice:** [N] months
- **Breaking change policy:** [Policy]
## Error Format
```json
{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Project with ID xyz not found",
"details": {}
}
}
```
## Developer Experience
- [ ] OpenAPI spec
- [ ] Interactive documentation
- [ ] SDKs: [Languages]
- [ ] Sandbox environment
- [ ] Quickstart guideFrequently asked questions
Generate instead of filling in templates
Connect your tools, and Vantage generates the content using real product data. Free to start.
Free to start. No credit card required.