API examples are the most valuable documentation. According to Nordic APIs, 80% of developers go straight to code examples before reading text. Well-crafted examples teach API usage faster than prose.
Request Example Checklist
| Element | Example |
|---|---|
| HTTP method | POST |
| Full URL | https://api.example.com/v1/users |
| Headers | Authorization: Bearer token |
| Body | {"name": "Sarah Chen"} |
Curl Template
curl -X POST https://api.example.com/v1/users \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Sarah Chen", "email": "sarah@example.com"}'
Error Responses to Include
| Status | When |
|---|---|
| 400 | Invalid data |
| 401 | Invalid auth |
| 404 | Not found |
| 429 | Rate limit |
Best Practices
- Use realistic data (sarah@example.com not foo@bar)
- Show complete requests with headers
- Format JSON with indentation
- Test every example
- Use example.com, never production URLs
FAQ
How many languages?
Curl plus your users' languages. Add JavaScript, Python at minimum.
Can AI help?
Yes, River's API Example Generator creates complete request/response pairs.