📡 API Responses & Data Structures
2 exercises — read JSON API responses and choose the best plain-English description for different audiences: junior developers, product managers, and QA engineers.
0 / 2 completed
Describing API responses in English
- Name the top-level structure: "This is a [success / error / paginated] response."
- Explain field purpose, not just the name: not "id field" → "a unique identifier for the user"
- Identify nested objects: "Inside 'preferences', there is an object that stores…"
- Explain HTTP status codes in words: 200 = success, 422 = validation error, 404 = not found
- Know your audience: engineers need technical detail; PMs need business meaning
1 / 2
A junior developer receives this JSON response from a REST API and asks what it represents. Which explanation is the most complete?
{
"data": {
"user": {
"id": "u_48f2a",
"name": "Olena Kovalenko",
"email": "olena@example.com",
"role": "admin",
"createdAt": "2023-11-15T09:30:00Z",
"preferences": {
"theme": "dark",
"language": "uk",
"notifications": true
}
}
},
"meta": {
"requestId": "req_9c21b",
"duration": 41
}
}Option B is the most complete and technically insightful explanation. It: (1) names the pattern — "data envelope" — which is standard in JSON API responses, (2) groups the user fields meaningfully (profile fields vs. nested preferences), (3) explains the purpose of each section ("UI settings", "debug/observability data"), (4) clarifies the unit for the duration field (milliseconds). Option A describes the structure but says nothing about what the fields mean. Option C is a structural inventory — it lists field names without explaining their business purpose or the API design patterns used. Option D is too brief to be useful. When describing API responses, identify: the envelope structure, the resource type, key field meanings, and any observability/meta patterns.
Keep practising: Describing Functions →