API Documentation Example
HTTP Status Codes
| Status Code | Description | Example Usage |
|---|---|---|
| 200 | OK | Successful GET, PUT, PATCH |
| 201 | Created | Successful POST |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Invalid request format |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Valid auth but insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 500 | Internal Server Error | Server-side error |
Request Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
id | String | Yes | Unique identifier | "abc123" |
name | String | Yes | Display name | "My Document" |
description | String | No | Optional description | "Document description" |
tags | Array | No | List of tags | ["tag1", "tag2"] |
active | Boolean | No | Whether item is active | true |
Error Response Format
| Field | Type | Description |
|---|---|---|
error | Object | Error details container |
error.code | String | Error code identifier |
error.message | String | Human-readable error message |
error.details | Array | Additional error details |
Permission Matrix
| Role | Read | Create | Update | Delete | Admin |
|---|---|---|---|---|---|
| Guest | ✓ | ✗ | ✗ | ✗ | ✗ |
| User | ✓ | ✓ | ✓ | ✗ | ✗ |
| Moderator | ✓ | ✓ | ✓ | ✓ | ✗ |
| Admin | ✓ | ✓ | ✓ | ✓ | ✓ |
Environment Configuration
| Environment | URL | Auth Required | Rate Limit |
|---|---|---|---|
| Development | https://dev-api.example.com | No | 1000/hour |
| Staging | https://staging-api.example.com | Yes | 5000/hour |
| Production | https://api.example.com | Yes | 10000/hour |