Skill: API Designer
Category: Dev Expert Used By: architect, backend-python, backend-go, backend-laravel
Overview
Design consistent, RESTful APIs with proper versioning, documentation, and error handling.
1. RESTful Conventions
| Method | Endpoint | Purpose | Response |
|---|
| GET | /users | List all | 200 + array |
| GET | /users/:id | Get one | 200 / 404 |
| POST | /users | Create | 201 + created |
| PUT | /users/:id | Replace | 200 / 404 |
| PATCH | /users/:id | Update | 200 / 404 |
| DELETE | /users/:id | Delete | 204 / 404 |
Nested Resources
GET /users/:userId/orders # User's orders
POST /users/:userId/orders # Create order for user
GET /users/:userId/orders/:orderId # Specific order
2. Naming Conventions
| Type | Convention | Example |
|---|
| Resources | Plural nouns | /users, /orders |
| Actions | Verbs (rare) | /auth/login, /reports/generate |
| Query params | snake_case | ?page_size=20 |
| Request/Response | camelCase | {"firstName": "John"} |
3. Versioning Strategies
| Strategy | Example | When to Use |
|---|
| URL Path | /v1/users | Most common, clear |
| Header | Accept: application/vnd.api+json;version=1 | Clean URLs |
| Query | /users?version=1 | Simple but messy |
Recommended: URL path (/api/v1/...)
4. Response Format
Success
{
"data": { "id": "123", "name": "John" },
"meta": { "timestamp": "2025-01-01T00:00:00Z" }
}
List with Pagination
{
"data": [{ "id": "1" }, { "id": "2" }],
"meta": {
"page": 1,
"pageSize": 20,
"total": 100,
"totalPages": 5
}
}
Error
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input",
"fields": { "email": "Invalid format" }
}
}
5. Status Codes
| Code | Meaning | When to Use |
|---|
| 200 | OK | Successful GET/PUT/PATCH |
| 201 | Created | Successful POST |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Invalid input |
| 401 | Unauthorized | No/invalid auth |
| 403 | Forbidden | No permission |
| 404 | Not Found | Resource missing |
| 409 | Conflict | Duplicate/state conflict |
| 422 | Unprocessable | Validation failed |
| 429 | Too Many | Rate limited |
| 500 | Server Error | Unexpected error |
6. Pagination Patterns
Offset-based (Simple)
GET /users?page=2&page_size=20
Cursor-based (Scalable)
GET /users?cursor=eyJpZCI6MTAwfQ&limit=20
| Pattern | Pros | Cons |
|---|
| Offset | Simple, jump to page | Slow on large datasets |
| Cursor | Consistent, fast | No page jumping |
7. Filtering & Sorting
# Filter
GET /users?status=active&role=admin
# Sort
GET /users?sort=created_at:desc,name:asc
# Search
GET /users?q=john
# Combined
GET /users?status=active&sort=name:asc&page=1&page_size=20
8. API Documentation (OpenAPI)
openapi: 3.0.0
info:
title: User API
version: 1.0.0
paths:
/users:
get:
summary: List users
parameters:
- name: page
in: query
schema: { type: integer, default: 1 }
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
9. API Design Checklist
- RESTful resource naming
- Consistent response format
- Proper status codes
- Pagination for lists
- Error responses with codes
- Versioning strategy
- OpenAPI documentation
- Rate limiting headers
Best Practices
Do's
- Use plural nouns for resources
- Return created/updated resource
- Include pagination metadata
- Document with OpenAPI
- Version from day one
Don'ts
- Use verbs in resource names
- Return different formats per endpoint
- Expose internal IDs/structures
- Ignore backward compatibility
- Skip error code standards
