API Design Spec Template for PMs

# API Design Spec Template

**API Name:** [Name]
**Version:** v1
**PM:** [Name]
**Tech Lead:** [Name]
**Date:** [Date]
**Status:** Draft / In Review / Approved

---

## 1. Purpose

> What does this API enable? Who are the consumers (mobile app, web frontend, third-party integrations)?

[Write here]

---

## 2. Base URL

| Environment | Base URL |
|---|---|
| Development | http://localhost:8000/api/v1 |
| Staging | https://staging-api.yourproduct.com/api/v1 |
| Production | https://api.yourproduct.com/api/v1 |

---

## 3. Authentication

| Method | Description |
|---|---|
| JWT Bearer Token | `Authorization: Bearer <token>` in header |
| API Key | `X-API-Key: <key>` in header (for server-to-server) |

Token expiry: 24 hours
Refresh mechanism: POST /auth/refresh with refresh_token

---

## 4. Endpoints

### [Resource Name]

#### List

```
GET /[resource]/
```

**Query Parameters:**
| Param | Type | Required | Description |
|---|---|---|---|
| page | integer | No | Default: 1 |
| page_size | integer | No | Default: 20, max: 100 |
| status | string | No | Filter by status |

**Response 200:**
```json
{
  "count": 42,
  "next": "/api/v1/[resource]/?page=2",
  "previous": null,
  "results": [
    {
      "id": "uuid",
      "name": "Example",
      "status": "active",
      "created_at": "2026-04-01T00:00:00Z"
    }
  ]
}
```

---

#### Create

```
POST /[resource]/
```

**Request Body:**
```json
{
  "name": "string (required, 3–255 chars)",
  "status": "active | archived (optional, default: active)"
}
```

**Response 201:**
```json
{
  "id": "uuid",
  "name": "Example",
  "status": "active",
  "created_at": "2026-04-01T00:00:00Z"
}
```

**Errors:**
| Status | Code | Message |
|---|---|---|
| 400 | VALIDATION_ERROR | name is required |
| 401 | UNAUTHORIZED | Token missing or expired |
| 403 | FORBIDDEN | User lacks permission |

---

#### Retrieve

```
GET /[resource]/{id}/
```

**Response 200:** Same as single object above.
**Response 404:** `{ "code": "NOT_FOUND", "message": "Resource not found" }`

---

#### Update

```
PATCH /[resource]/{id}/
```

Partial update — only fields provided are updated.

---

#### Delete

```
DELETE /[resource]/{id}/
```

**Response 204:** No body.

---

## 5. Error Format

All errors return a consistent structure:

```json
{
  "code": "ERROR_CODE",
  "message": "Human-readable description",
  "details": {}
}
```

| HTTP Status | Code | When |
|---|---|---|
| 400 | VALIDATION_ERROR | Request body fails validation |
| 401 | UNAUTHORIZED | Missing or invalid token |
| 403 | FORBIDDEN | Valid token but insufficient permissions |
| 404 | NOT_FOUND | Resource doesn't exist |
| 409 | CONFLICT | Duplicate resource or state conflict |
| 429 | RATE_LIMITED | Too many requests |
| 500 | INTERNAL_ERROR | Unexpected server error |

---

## 6. Rate Limits

| Endpoint Group | Limit | Window |
|---|---|---|
| Auth endpoints | 10 requests | per minute |
| Read endpoints | 1,000 requests | per hour |
| Write endpoints | 100 requests | per hour |

Rate limit headers returned on all responses:
- `X-RateLimit-Limit`
- `X-RateLimit-Remaining`
- `X-RateLimit-Reset`

---

## 7. Versioning Strategy

- Current version: **v1**
- Breaking changes get a new version (v2)
- Non-breaking additions (new optional fields, new endpoints) can be added to v1
- v1 will be supported for minimum 12 months after v2 launches
- Deprecation announced via API response header: `Deprecation: true`

---

## 8. Pagination

All list endpoints use cursor-based or page-based pagination:

| Type | When to Use |
|---|---|
| Page-based | < 10,000 records, user-facing tables |
| Cursor-based | > 10,000 records, infinite scroll, exports |

---

## 9. Open Questions

| Question | Owner | Due |
|---|---|---|
| | | |