Initial commit
This commit is contained in:
Zhongwei Li
@@ -0,0 +1,373 @@
|
||||
# API Specification: {{PROJECT_NAME}}
|
||||
|
||||
**Document Version:** 1.0
|
||||
**Date:** {{DATE}}
|
||||
**Status:** {{STATUS}}
|
||||
**OpenAPI Version:** 3.0.3
|
||||
|
||||
<!-- SCOPE: API endpoints (methods, paths, parameters, responses), authentication mechanisms (JWT, OAuth2, API keys), error codes (HTTP status + custom codes), rate limiting, API versioning ONLY. -->
|
||||
<!-- DO NOT add here: Database schema → database_schema.md, Tech stack versions → tech_stack.md, Architecture patterns → architecture.md, Requirements → requirements.md, Deployment → runbook.md, Design system → design_guidelines.md -->
|
||||
|
||||
---
|
||||
|
||||
## 1. API Overview
|
||||
|
||||
### 1.1 Base URL
|
||||
{{BASE_URL}}
|
||||
<!-- Example: Development: http://localhost:3000/api/v1, Production: https://api.example.com/v1 -->
|
||||
|
||||
### 1.2 API Design Principles
|
||||
{{API_DESIGN_PRINCIPLES}}
|
||||
<!-- Example: RESTful design, Stateless communication, JSON request/response format, HATEOAS links for discoverability, Consistent error handling -->
|
||||
|
||||
### 1.3 API Versioning
|
||||
{{API_VERSIONING}}
|
||||
<!-- Example: URI versioning (/api/v1/, /api/v2/), Deprecation policy (6 months notice), Backward compatibility for minor updates -->
|
||||
|
||||
---
|
||||
|
||||
## 2. Authentication & Authorization
|
||||
|
||||
### 2.1 Authentication Methods
|
||||
|
||||
**Supported Methods:**
|
||||
{{AUTH_METHODS}}
|
||||
<!-- Example: JWT Bearer tokens (primary), OAuth2 (Google, GitHub), API Keys (for service-to-service) -->
|
||||
|
||||
**JWT Token Format:**
|
||||
```json
|
||||
{
|
||||
"header": {
|
||||
"alg": "HS256",
|
||||
"typ": "JWT"
|
||||
},
|
||||
"payload": {
|
||||
"sub": "user_id",
|
||||
"role": "admin",
|
||||
"exp": 1234567890
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Token Expiration:**
|
||||
{{TOKEN_EXPIRATION}}
|
||||
<!-- Example: Access token: 1 hour, Refresh token: 30 days -->
|
||||
|
||||
### 2.2 Authorization (RBAC)
|
||||
|
||||
**Roles:**
|
||||
{{RBAC_ROLES}}
|
||||
<!-- Example:
|
||||
| Role | Permissions | Description |
|
||||
|------|-------------|-------------|
|
||||
| Admin | Full access | System administration |
|
||||
| Editor | Read, Create, Update | Content management |
|
||||
| Viewer | Read only | View-only access |
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
## 3. API Endpoints
|
||||
|
||||
### 3.1 Authentication Endpoints
|
||||
|
||||
| Method | Endpoint | Description | Auth Required |
|
||||
|--------|----------|-------------|---------------|
|
||||
| POST | `/auth/register` | Register new user | No |
|
||||
| POST | `/auth/login` | Login (email/password) | No |
|
||||
| POST | `/auth/refresh` | Refresh access token | Yes (Refresh token) |
|
||||
| POST | `/auth/logout` | Logout (invalidate tokens) | Yes |
|
||||
| GET | `/auth/me` | Get current user info | Yes |
|
||||
|
||||
**Example: POST /auth/login**
|
||||
|
||||
Request:
|
||||
```json
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"password": "secure_password"
|
||||
}
|
||||
```
|
||||
|
||||
Response (200 OK):
|
||||
```json
|
||||
{
|
||||
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"expiresIn": 3600,
|
||||
"user": {
|
||||
"id": "uuid",
|
||||
"email": "user@example.com",
|
||||
"role": "editor"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.2 User Management Endpoints
|
||||
|
||||
| Method | Endpoint | Description | Auth Required | Roles |
|
||||
|--------|----------|-------------|---------------|-------|
|
||||
| GET | `/users` | List all users (paginated) | Yes | Admin |
|
||||
| GET | `/users/:id` | Get user by ID | Yes | Admin, self |
|
||||
| PUT | `/users/:id` | Update user | Yes | Admin, self |
|
||||
| DELETE | `/users/:id` | Delete user | Yes | Admin |
|
||||
| PATCH | `/users/:id/password` | Change password | Yes | Admin, self |
|
||||
|
||||
**Example: GET /users?page=1&limit=20**
|
||||
|
||||
Response (200 OK):
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"email": "user@example.com",
|
||||
"role": "editor",
|
||||
"createdAt": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"total": 150,
|
||||
"totalPages": 8
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.3 {{RESOURCE_1}} Endpoints
|
||||
|
||||
| Method | Endpoint | Description | Auth Required |
|
||||
|--------|----------|-------------|---------------|
|
||||
| GET | `/{{resource}}` | List {{resource}} | Yes |
|
||||
| GET | `/{{resource}}/:id` | Get {{resource}} by ID | Yes |
|
||||
| POST | `/{{resource}}` | Create {{resource}} | Yes |
|
||||
| PUT | `/{{resource}}/:id` | Update {{resource}} | Yes |
|
||||
| DELETE | `/{{resource}}/:id` | Delete {{resource}} | Yes |
|
||||
|
||||
<!-- Example: Products
|
||||
| GET | `/products` | List products | Yes |
|
||||
| GET | `/products/:id` | Get product by ID | Yes |
|
||||
| POST | `/products` | Create product | Yes (Editor+) |
|
||||
| PUT | `/products/:id` | Update product | Yes (Editor+) |
|
||||
| DELETE | `/products/:id` | Delete product | Yes (Admin) |
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
### 3.4 {{RESOURCE_2}} Endpoints
|
||||
|
||||
{{RESOURCE_2_ENDPOINTS}}
|
||||
<!-- Repeat structure from 3.3 for additional resources: Orders, Categories, etc. -->
|
||||
|
||||
---
|
||||
|
||||
## 4. Request & Response Formats
|
||||
|
||||
### 4.1 Common Query Parameters
|
||||
|
||||
| Parameter | Type | Description | Example |
|
||||
|-----------|------|-------------|---------|
|
||||
| `page` | integer | Page number (1-based) | `?page=2` |
|
||||
| `limit` | integer | Items per page (max 100) | `?limit=50` |
|
||||
| `sort` | string | Sort field (+asc, -desc) | `?sort=-createdAt` |
|
||||
| `filter` | string | Filter expression | `?filter=status:active` |
|
||||
| `search` | string | Search query | `?search=keyword` |
|
||||
|
||||
### 4.2 Standard Response Structure
|
||||
|
||||
**Success Response:**
|
||||
```json
|
||||
{
|
||||
"data": { /* resource data */ },
|
||||
"meta": { /* metadata, pagination */ }
|
||||
}
|
||||
```
|
||||
|
||||
**Error Response:**
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "ERROR_CODE",
|
||||
"message": "Human-readable error message",
|
||||
"details": [ /* validation errors, if applicable */ ]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Error Codes
|
||||
|
||||
### 5.1 HTTP Status Codes
|
||||
|
||||
| Status | Meaning | When Used |
|
||||
|--------|---------|-----------|
|
||||
| 200 | OK | Successful GET, PUT, PATCH |
|
||||
| 201 | Created | Successful POST |
|
||||
| 204 | No Content | Successful DELETE |
|
||||
| 400 | Bad Request | Invalid request format, validation errors |
|
||||
| 401 | Unauthorized | Missing or invalid authentication token |
|
||||
| 403 | Forbidden | Authenticated but insufficient permissions |
|
||||
| 404 | Not Found | Resource not found |
|
||||
| 409 | Conflict | Duplicate resource (email already exists) |
|
||||
| 422 | Unprocessable Entity | Validation errors |
|
||||
| 429 | Too Many Requests | Rate limit exceeded |
|
||||
| 500 | Internal Server Error | Unexpected server error |
|
||||
|
||||
### 5.2 Custom Error Codes
|
||||
|
||||
| Code | HTTP Status | Description | Example |
|
||||
|------|-------------|-------------|---------|
|
||||
| `AUTH_INVALID_CREDENTIALS` | 401 | Invalid email/password | Login failed |
|
||||
| `AUTH_TOKEN_EXPIRED` | 401 | JWT token expired | Token needs refresh |
|
||||
| `AUTH_INSUFFICIENT_PERMISSIONS` | 403 | User lacks required role | Admin-only action |
|
||||
| `VALIDATION_FAILED` | 422 | Input validation failed | Missing required field |
|
||||
| `RESOURCE_NOT_FOUND` | 404 | Requested resource not found | User ID not found |
|
||||
| `RESOURCE_CONFLICT` | 409 | Resource already exists | Email already registered |
|
||||
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests | 100 req/min limit hit |
|
||||
|
||||
**Example Error Response:**
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "VALIDATION_FAILED",
|
||||
"message": "Validation failed for request body",
|
||||
"details": [
|
||||
{
|
||||
"field": "email",
|
||||
"message": "Invalid email format"
|
||||
},
|
||||
{
|
||||
"field": "password",
|
||||
"message": "Password must be at least 8 characters"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Rate Limiting
|
||||
|
||||
**Limits:**
|
||||
{{RATE_LIMITS}}
|
||||
<!-- Example:
|
||||
| Endpoint Type | Limit | Window |
|
||||
|--------------|-------|--------|
|
||||
| Authentication | 5 requests | 15 minutes |
|
||||
| Read (GET) | 100 requests | 1 minute |
|
||||
| Write (POST/PUT/DELETE) | 30 requests | 1 minute |
|
||||
-->
|
||||
|
||||
**Rate Limit Headers:**
|
||||
```
|
||||
X-RateLimit-Limit: 100
|
||||
X-RateLimit-Remaining: 75
|
||||
X-RateLimit-Reset: 1640000000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Pagination
|
||||
|
||||
**Request:**
|
||||
```
|
||||
GET /users?page=2&limit=20
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"data": [ /* 20 users */ ],
|
||||
"pagination": {
|
||||
"page": 2,
|
||||
"limit": 20,
|
||||
"total": 150,
|
||||
"totalPages": 8,
|
||||
"hasNext": true,
|
||||
"hasPrev": true
|
||||
},
|
||||
"links": {
|
||||
"self": "/users?page=2&limit=20",
|
||||
"first": "/users?page=1&limit=20",
|
||||
"prev": "/users?page=1&limit=20",
|
||||
"next": "/users?page=3&limit=20",
|
||||
"last": "/users?page=8&limit=20"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. OpenAPI Specification
|
||||
|
||||
**OpenAPI Documentation:**
|
||||
{{OPENAPI_LINK}}
|
||||
<!-- Example: Swagger UI available at `/api-docs`, OpenAPI JSON at `/api-docs.json` -->
|
||||
|
||||
**Example OpenAPI Snippet (users endpoint):**
|
||||
```yaml
|
||||
paths:
|
||||
/users:
|
||||
get:
|
||||
summary: List all users
|
||||
tags: [Users]
|
||||
security:
|
||||
- bearerAuth: []
|
||||
parameters:
|
||||
- name: page
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
default: 1
|
||||
- name: limit
|
||||
in: query
|
||||
schema:
|
||||
type: integer
|
||||
default: 20
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/User'
|
||||
pagination:
|
||||
$ref: '#/components/schemas/Pagination'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Maintenance
|
||||
|
||||
**Last Updated:** {{DATE}}
|
||||
|
||||
**Update Triggers:**
|
||||
- New API endpoints added
|
||||
- Authentication/authorization changes
|
||||
- Error code modifications
|
||||
- Rate limiting adjustments
|
||||
- API versioning (major/minor releases)
|
||||
|
||||
**Verification:**
|
||||
- [ ] All endpoints documented with methods/paths/params/responses
|
||||
- [ ] Authentication requirements specified for each endpoint
|
||||
- [ ] Error codes match implementation
|
||||
- [ ] OpenAPI specification up to date
|
||||
- [ ] Rate limits tested and validated
|
||||
|
||||
---
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Template Last Updated:** 2025-11-16
|
||||
Reference in New Issue
Block a user