Challenge: Identify & Correct Missing Pieces in an API Reference
Scenario: You have incomplete API documentation for an endpoint that retrieves user details. Your task is to find what’s missing or unclear and propose improvements.
Incomplete API Documentation:
### GET /v1/users/{userId}
Retrieves a single user's details.
**Path Parameters**:
- userId
**Example Request**:
GET /v1/users/12345 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
Response: 200 OK
{
"id": 12345,
"name": "John Doe",
"email": "john@example.com"
}
Observations:
- The documentation lacks details on error responses (e.g., if the user is not found).
- No information about required headers beyond `Authorization`.
- No details on potential query parameters or rate limits.
Tasks:
- Identify at least 3–5 missing or unclear points.
- Rewrite the API documentation with complete details.
- Clearly state any assumptions you make.
Hint: Consider adding error codes, request validation rules, and example responses for failures.
Solution: Complete API Documentation
Missing Information:
- Lack of error responses: No mention of 404, 401, or other failure scenarios.
- Unclear userId format: It doesn’t specify whether it’s an integer, string, or UUID.
- No mention of authentication details: Is the Authorization header mandatory?
- Missing query parameters: Are there optional filters like `expand`?
- Rate limiting details absent: Does the API restrict request frequency?
Revised API Documentation:
1. Endpoint & Method
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/users/{userId} | Retrieves a single user's details |
2. Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| userId | Integer | Yes | Unique identifier of the user |
3. Example Request
GET /v1/users/12345 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
4. Response
HTTP/1.1 200 OK
{
"id": 12345,
"name": "John Doe",
"email": "john@example.com"
}
5. Error Responses
| HTTP Code | Message | Description |
|---|---|---|
| 401 | Unauthorized | Invalid or missing authorization token |
| 404 | User Not Found | The specified userId does not exist |
| 429 | Rate Limit Exceeded | Too many requests in a short period |
Found value in the course? Your support fuels my work!
Course completed
Have an issue? Please provide specific feedback by reporting an issue.