engineering
API Design Guide
Design RESTful and GraphQL APIs with consistent naming conventions, versioning strategy, pagination patterns, error response formats, authentication schemes, and rate limiting — producing a complete API specification.
api-designRESTGraphQLendpointsversioningdocumentation
Works well with agents
$ npx skills add The-AI-Directory-Company/(…) --skill api-design-guideapi-design-guide/
task-management-api.md
Markdown
| 1 | # Task Management API — Design Specification |
| 2 | |
| 3 | ## Overview |
| 4 | |
| 5 | RESTful API for a task management system. Consumers: SPA frontend, mobile apps, third-party integrations via API keys. Auth: OAuth 2.0 + PKCE for users, API keys for service accounts. |
| 6 | |
| 7 | ## 1. Resources |
| 8 | |
| 9 | | Resource | Path | Description | |
| 10 | |----------|------|-------------| |
| 11 | | Projects | `/v1/projects` | Top-level container for tasks | |
| 12 | | Tasks | `/v1/projects/{project_id}/tasks` | Work items within a project | |
| 13 | | Comments | `/v1/tasks/{task_id}/comments` | Discussion on a task | |
| 14 | | Labels | `/v1/labels` | Shared labels across projects | |
| 15 | |
| 16 | ## 2. Endpoints |
| 17 | |
| 18 | ### Projects |
| 19 | |
| 20 | | Method | Path | Description | Auth | Success | |
| 21 | |--------|------|-------------|------|---------| |
| 22 | | GET | `/v1/projects` | List user's projects | Bearer | 200 | |
| 23 | | POST | `/v1/projects` | Create a project | Bearer | 201 | |
| 24 | | GET | `/v1/projects/{id}` | Get project details | Bearer | 200 | |
| 25 | | PATCH | `/v1/projects/{id}` | Update project fields | Bearer | 200 | |
| 26 | | DELETE | `/v1/projects/{id}` | Archive project (soft delete) | Bearer | 204 | |
| 27 | |
| 28 | ### Tasks |
| 29 | |
| 30 | | Method | Path | Description | Auth | Success | |
| 31 | |--------|------|-------------|------|---------| |
| 32 | | GET | `/v1/projects/{id}/tasks` | List tasks (filterable) | Bearer | 200 | |
| 33 | | POST | `/v1/projects/{id}/tasks` | Create a task | Bearer | 201 | |
| 34 | | GET | `/v1/tasks/{id}` | Get task details | Bearer | 200 | |
| 35 | | PATCH | `/v1/tasks/{id}` | Update task fields | Bearer | 200 | |
| 36 | | DELETE | `/v1/tasks/{id}` | Delete task | Bearer | 204 | |
| 37 | | POST | `/v1/tasks/{id}/complete` | Mark task complete | Bearer | 200 | |
| 38 | |
| 39 | ## 3. Request/Response Examples |
| 40 | |
| 41 | **Create Task** — `POST /v1/projects/proj_01/tasks` |
| 42 | ```json |
| 43 | { |
| 44 | "title": "Design login page", |
| 45 | "description": "Implement OAuth flow with Google and GitHub providers", |
| 46 | "assignee_id": "usr_42", |
| 47 | "due_date": "2025-10-15", |
| 48 | "priority": "high", |
| 49 | "label_ids": ["lbl_03", "lbl_07"] |
| 50 | } |
| 51 | ``` |
| 52 | |
| 53 | **Response** — `201 Created` |
| 54 | ```json |
| 55 | { |
| 56 | "data": { |
| 57 | "id": "tsk_291", |
| 58 | "title": "Design login page", |
| 59 | "status": "open", |
| 60 | "priority": "high", |
| 61 | "assignee": { "id": "usr_42", "name": "Priya Sharma" }, |
| 62 | "due_date": "2025-10-15", |
| 63 | "created_at": "2025-09-01T14:32:00Z" |
| 64 | } |
| 65 | } |
| 66 | ``` |
| 67 | |
| 68 | **List Tasks** — `GET /v1/projects/proj_01/tasks?status=open&priority=high&cursor=eyJpZCI6MzB9&limit=20` |
| 69 | |
| 70 | **Response** — `200 OK` |
| 71 | ```json |
| 72 | { |
| 73 | "data": [{ "id": "tsk_291", "title": "Design login page", "status": "open" }], |
| 74 | "meta": { "total": 84, "limit": 20, "next_cursor": "eyJpZCI6NTB9" } |
| 75 | } |
| 76 | ``` |
| 77 | |
| 78 | ## 4. Error Handling |
| 79 | |
| 80 | All errors use a consistent envelope: |
| 81 | ```json |
| 82 | { |
| 83 | "error": { |
| 84 | "code": "RESOURCE_NOT_FOUND", |
| 85 | "message": "Task tsk_999 does not exist or you do not have access.", |
| 86 | "request_id": "req_abc123" |
| 87 | } |
| 88 | } |
| 89 | ``` |
| 90 | |
| 91 | | Status | Code | When | |
| 92 | |--------|------|------| |
| 93 | | 400 | VALIDATION_ERROR | Missing required field, invalid date format | |
| 94 | | 401 | UNAUTHENTICATED | Missing or expired token | |
| 95 | | 403 | FORBIDDEN | User lacks permission on this project | |
| 96 | | 404 | RESOURCE_NOT_FOUND | Task/project does not exist or no access | |
| 97 | | 409 | CONFLICT | Task already completed (idempotency) | |
| 98 | | 429 | RATE_LIMITED | Exceeded request quota | |
| 99 | |
| 100 | ## 5. Pagination |
| 101 | |
| 102 | Cursor-based for all collection endpoints. Default limit: 20, max: 100. Responses include `next_cursor` (null on last page). Filtering via query params: `status`, `priority`, `assignee_id`, `due_before`, `due_after`. |
| 103 | |
| 104 | ## 6. Rate Limiting |
| 105 | |
| 106 | | Tier | Limit | Window | |
| 107 | |------|-------|--------| |
| 108 | | Free | 100 req | 1 minute | |
| 109 | | Pro | 1,000 req | 1 minute | |
| 110 | | API key (service) | 5,000 req | 1 minute | |
| 111 | |
| 112 | Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (Unix timestamp). |
| 113 | |
| 114 | ## 7. Versioning |
| 115 | |
| 116 | URL-prefix versioning (`/v1/`). Breaking changes require a new major version. Field additions within a version are non-breaking. Deprecated versions supported for 12 months with 90-day advance notice via changelog and `Sunset` header. |
| 117 |