API Endpoint Documenter
Generate professional REST API endpoint documentation.
REST API Documentation Best Practices
Clear API documentation is essential for developers to understand and use your API effectively. Follow these best practices for professional API documentation.
Essential Elements
1. Endpoint Description
Clearly explain what the endpoint does:
- What resource it operates on
- What action it performs
- When to use this endpoint
- Any side effects or important notes
2. HTTP Method
- GET: Retrieve data (read-only, idempotent)
- POST: Create new resources
- PUT: Update/replace entire resource
- PATCH: Partial update of resource
- DELETE: Remove resource
3. Authentication Requirements
Document how to authenticate:
- Type of authentication (Bearer, API Key, OAuth)
- Where to include credentials (header, query param)
- How to obtain authentication credentials
- Permission/scope requirements
Parameters Documentation
| Parameter Type | Location | Example |
|---|---|---|
| Path Parameters | In URL path | /users/{id} |
| Query Parameters | After ? in URL | /users?page=1&limit=10 |
| Request Body | HTTP body (POST/PUT) | {"name": "John"} |
| Headers | HTTP headers | Authorization: Bearer token |
Response Documentation
Document all possible responses including:
- 200 OK: Request succeeded
- 201 Created: Resource created successfully
- 204 No Content: Success with no response body
- 400 Bad Request: Invalid request format
- 401 Unauthorized: Authentication required
- 403 Forbidden: Insufficient permissions
- 404 Not Found: Resource doesn't exist
- 422 Unprocessable Entity: Validation errors
- 429 Too Many Requests: Rate limit exceeded
- 500 Internal Server Error: Server-side error
- 503 Service Unavailable: Temporary downtime
Example: Complete Endpoint Documentation
## POST /api/v1/users
Creates a new user account.
**Authentication:** Bearer Token (requires `users:write` scope)
### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | User's full name (2-100 chars) |
| email | string | Yes | Valid email address |
| role | string | No | User role (default: "user") |
### Example Request
```bash
curl -X POST https://api.example.com/api/v1/users \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"name": "John Doe",
"email": "john@example.com",
"role": "admin"
}'
```
### Responses
**201 Created**
```json
{
"id": "usr_123456",
"name": "John Doe",
"email": "john@example.com",
"role": "admin",
"created_at": "2024-03-15T10:30:00Z"
}
```
**400 Bad Request**
```json
{
"error": "validation_error",
"message": "Invalid email format",
"fields": {
"email": "Must be a valid email address"
}
}
```
**401 Unauthorized**
```json
{
"error": "unauthorized",
"message": "Invalid or expired token"
}
```Documentation Tools
- OpenAPI/Swagger: Industry standard for API documentation
- Postman: API testing and documentation
- ReadMe: API documentation platform
- Stoplight: API design and documentation
- Redoc: Generate docs from OpenAPI specs
Quick Tips
- Use consistent naming conventions
- Version your API (v1, v2)
- Document rate limits
- Provide working code examples
- Include error response examples
- Keep docs up to date with code
- Test all examples before publishing
HTTP Status Codes
Success:
- 200 - OK
- 201 - Created
- 204 - No Content
Client Errors:
- 400 - Bad Request
- 401 - Unauthorized
- 403 - Forbidden
- 404 - Not Found
Server Errors:
- 500 - Internal Error
- 503 - Unavailable