When a user needs API documentation:
- Gather API Information:
- API type (REST, GraphQL, WebSocket, gRPC)?
- Authentication method (API key, OAuth, JWT)?
- Base URL and versioning strategy?
- Available endpoints and their purposes?
- Request/response formats?
- Rate limiting or usage restrictions?
- Generate Complete Documentation Structure:
Overview Section:
- What the API does (1-2 sentences)
- Key capabilities
- Getting started checklist
- Support and resources
Authentication:
- How to obtain credentials
- Where to include auth tokens
- Example authenticated request
- Token refresh process (if applicable)
Base URL & Versioning:
- Production and sandbox URLs
- Version format (path, header, query param)
- Current version and changelog link
Endpoints (for each endpoint):
- HTTP method and path
- Description of what it does
- Path parameters
- Query parameters
- Request headers
- Request body schema
- Response codes and meanings
- Response body schema
- Example request (curl, JavaScript, Python)
- Example response (formatted JSON)
Error Handling:
- Standard error response format
- Common error codes and meanings
- Troubleshooting guide
Rate Limiting:
- Limits and windows
- Headers to check
- How to handle rate limit errors
SDKs & Libraries:
- Official client libraries
- Community libraries
- Installation instructions
Webhooks (if applicable):
- Available webhook events
- Setup process
- Payload examples
- Security verification
- Format Output (REST API example):
```markdown
# [API Name] Documentation
## Overview
[Brief description of what the API does]
Base URL: https://api.example.com/v1
Authentication: API Key via Authorization header
## Quick Start
1. [Step 1]
2. [Step 2]
3. [Step 3]
## Authentication
All requests require an API key in the Authorization header:
```
Authorization: Bearer YOUR_API_KEY
```
Get your API key from [dashboard link].
## Endpoints
### GET /resource
Retrieve a list of resources.
Parameters:
- limit (optional, integer): Number of results (max 100, default 10)
- offset (optional, integer): Pagination offset (default 0)
- filter (optional, string): Filter by field
Request Example:
```bash
curl -X GET "https://api.example.com/v1/resource?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
```
Response (200 OK):
```json
{
"data": [
{
"id": "123",
"name": "Example",
"created_at": "2024-01-15T10:00:00Z"
}
],
"total": 100,
"limit": 10,
"offset": 0
}
```
Response Codes:
- 200 - Success
- 400 - Bad request (invalid parameters)
- 401 - Unauthorized (invalid API key)
- 429 - Rate limit exceeded
- 500 - Server error
### POST /resource
Create a new resource.
Request Body:
```json
{
"name": "string (required)",
"description": "string (optional)",
"metadata": "object (optional)"
}
```
Request Example:
```bash
curl -X POST "https://api.example.com/v1/resource" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My Resource",
"description": "A test resource"
}'
```
Response (201 Created):
```json
{
"id": "124",
"name": "My Resource",
"description": "A test resource",
"created_at": "2024-01-15T10:30:00Z"
}
```
## Error Handling
All errors follow this format:
```json
{
"error": {
"code": "invalid_request",
"message": "The 'name' field is required",
"details": {
"field": "name"
}
}
}
```
Common Error Codes:
- invalid_request - Malformed request
- authentication_failed - Invalid API key
- not_found - Resource doesn't exist
- rate_limit_exceeded - Too many requests
- internal_error - Server error
## Rate Limiting
Limits: 1000 requests per hour
Headers:
- X-RateLimit-Limit: Total requests allowed
- X-RateLimit-Remaining: Requests remaining
- X-RateLimit-Reset: Timestamp when limit resets
When rate limited, you'll receive a 429 status code.
## Code Examples
### JavaScript (Node.js)
```javascript
const response = await fetch('https://api.example.com/v1/resource', {
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
});
const data = await response.json();
```
### Python
```python
import requests
response = requests.get(
'https://api.example.com/v1/resource',
headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()
```
## Support
- Documentation: https://docs.example.com
- Support: support@example.com
- Status: https://status.example.com
```
- For GraphQL APIs, adapt to show:
- Schema definitions
- Query examples
- Mutation examples
- Subscription examples
- Variables and directives
- Documentation Best Practices:
- Start with working example (copy-paste ready)
- Show both request and response
- Use realistic example data
- Include error cases
- Explain every parameter
- Provide code examples in multiple languages
- Use consistent formatting
- Add "Try it" interactive examples when possible
- Link related endpoints
- Include changelog and versioning
- Developer Experience Tips:
- Include a "Quick Start" with working example in 60 seconds
- Provide Postman collection or OpenAPI spec
- Show common use cases and workflows
- Include troubleshooting section
- Add testing/sandbox environment
- Provide SDKs with installation instructions
- Include rate limiting details upfront
- Show pagination patterns
- Explain filtering and sorting options
|