API Design
Design consistent, well-documented APIs across REST, GraphQL, gRPC, and CLI interfaces.
When to Use
- Designing new API endpoints or commands
- Reviewing existing API contracts for consistency
- Establishing API naming and versioning conventions
- Planning backward-compatible API changes
- Generating API documentation or OpenAPI specs
Principles
- Consistency - Same patterns everywhere (naming, error format, pagination)
- Discoverability - A developer should guess the right endpoint/flag without reading docs
- Backward compatibility - Additions are safe; removals and renames require versioning
- Minimal surface - Expose only what consumers need; internal details stay internal
- Self-describing errors - Error responses should tell the caller what went wrong and how to fix it
REST API Checklist
Naming
- Use plural nouns for resources:
/users,/tasks - Use kebab-case for multi-word paths:
/user-settings - Nest for ownership:
/users/{id}/tasks - Use verbs only for actions that don't map to CRUD:
/tasks/{id}/approve
HTTP Methods
| Method | Purpose | Idempotent |
|---|---|---|
| GET | Read | Yes |
| POST | Create / action | No |
| PUT | Full replace | Yes |
| PATCH | Partial update | Yes |
| DELETE | Remove | Yes |
Response Format
{
"data": { ... },
"meta": { "page": 1, "total": 42 }
}Error format:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Human-readable description",
"details": [
{ "field": "email", "reason": "required" }
]
}
}Status Codes
| Code | Use |
|---|---|
| 200 | Success (with body) |
| 201 | Created |
| 204 | Success (no body) |
| 400 | Client error (validation) |
| 401 | Not authenticated |
| 403 | Not authorized |
| 404 | Not found |
| 409 | Conflict (duplicate, state mismatch) |
| 422 | Unprocessable (semantically invalid) |
| 500 | Server error |
Pagination
Use cursor-based for large datasets, offset-based for simple cases:
GET /tasks?cursor=abc123&limit=20
GET /tasks?page=2&per_page=20Versioning
- Prefer URL prefix:
/v1/tasks,/v2/tasks - Use header-based only when URL versioning is impractical
CLI API Checklist
Command Structure
<tool> <noun> <verb> [args] [--flags]Example: synapse send gemini "Review code" --wait
Flag Conventions
- Long form:
--output,--verbose - Short form for common flags:
-o,-v - Boolean flags:
--force,--no-color - Repeatable:
--attach file1 --attach file2 - Mutually exclusive groups:
--wait | --notify | --silent
Output
- Default: human-readable
--json: machine-readable JSON--quiet/-q: minimal output- Exit codes: 0 = success, 1 = error, 2 = usage error
Workflow
Step 1: Define Resources / Commands
List the entities and actions the API must support.
Step 2: Map to Endpoints / Subcommands
Apply naming conventions to produce the API surface.
Step 3: Define Request / Response Schemas
Specify required and optional fields, types, and validation rules.
Step 4: Document Error Cases
For each endpoint, list possible error responses and their meaning.
Step 5: Review for Consistency
Cross-check naming, error format, and pagination across all endpoints.