Beginner REST API Documentation Exercises
Master the art of API documentation with these 5 practical exercises. Learn to document endpoints, parameters, authentication, and error responses with real-world scenarios designed for beginners.
Table of Contents
You’ve done a fantastic job learning how to structure and write API documentation that is clear, concise, and developer-friendly. But let’s be honest—the best way to learn is by doing.
This section is all about getting your hands dirty with real API documentation challenges.
What You’ll Practice in These Exercises
In this chapter, you’ll work through 5 practical exercises that will strengthen your API documentation skills:
- Document complete API endpoints with parameters and response fields
- Create professional parameter tables with proper formatting and descriptions
- Write clear authentication instructions for different API security methods
- Build example requests using cURL and code samples
- Structure error responses that help developers troubleshoot effectively
Each exercise builds on the previous one—so by the end, you’ll have solid experience documenting REST APIs from start to finish.
How These Exercises Work
Each exercise follows this structure:
- A real-world scenario providing context for the documentation task
- Technical details about the API you need to document
- Specific requirements for what you need to include
- A sample solution for comparison after you complete your attempt
This format mirrors how you’ll receive API documentation assignments in the real world, where you’ll often get technical information and need to transform it into clear, developer-friendly documentation.
Exercise Overview
| Exercise | Focus Area | Key Skills Practiced | Difficulty |
|---|---|---|---|
| Exercise 1 | Weather Forecast API | Basic endpoint documentation, parameter tables | Easy |
| Exercise 2 | User Management API | Authentication, request/response examples | Easy |
| Exercise 3 | E-commerce Product API | Complex parameters, CRUD operations | Medium |
| Exercise 4 | Social Media API | Error handling, status codes, pagination | Medium |
| Exercise 5 | Payment Processing API | Security, comprehensive documentation | Medium |
Tips for Completing the Exercises
Before diving into the exercises, keep these best practices in mind:
- Read through all requirements before starting each exercise
- Structure your documentation with clear headings and organization
- Use tables for parameters, response fields, and error codes
- Include examples that demonstrate real-world usage
- Focus on clarity by using concise, developer-friendly language
- Compare your work with the solution only after you’ve completed your version
Remember, there’s no single “perfect” way to document an API. Your solution might differ from the provided one while still being excellent. The goal is to practice communicating technical information clearly and consistently.
Let’s Get Started!
Each exercise below can be expanded to view the requirements and solution. Challenge yourself to complete each one before looking at the solution.
1 Documenting a Weather API
Exercise 1: Documenting a Weather API
Scenario: You are assigned to document the **Weather Forecast API**, which provides real-time weather updates for a given city.
Your Task: Write an API reference document covering:
- Overview of the API.
- Endpoints and HTTP methods.
- Request parameters in a structured table.
- An example API request (including cURL and why it's used).
- A sample response from the API.
- Response parameters in a structured table.
- Possible error codes and troubleshooting guidance.
Provided API Code:
Below is a sample API request and response:
API Request:
GET https://api.weatherforecast.com/weather?city=London&units=metric&apikey=your_api_key
Sample Response:
{
"city": "London",
"temperature": "15°C",
"humidity": "72%",
"wind_speed": "10 km/h",
"condition": "Partly Cloudy"
}
Bonus Challenge: Add details about rate limits and authentication (if applicable).
Solution to Exercise 1
1. Overview
The **Weather Forecast API** provides real-time weather information for a given city. It delivers weather conditions such as temperature, humidity, and wind speed. This API is ideal for developers building weather-based applications or services.
2. Endpoints and Methods
GET /weather – Retrieves current weather data for a specified city.
3. Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| city | String | Yes | None | Name of the city to fetch weather data for. |
| units | String | No | Kelvin | Units for temperature (e.g., "metric" for Celsius, "imperial" for Fahrenheit). |
| apikey | String | Yes | None | API key for authentication. |
4. Sample cURL Request
Why Use cURL? cURL is a command-line tool used to make API requests without a web browser. It helps developers test APIs quickly and automate requests in scripts.
curl -X GET "https://api.weatherforecast.com/weather?city=London&units=metric&apikey=your_api_key" -H "Accept: application/json"
5. Response Parameters
| Parameter | Type | Description |
|---|---|---|
| city | String | Name of the city. |
| temperature | String | Current temperature with units. |
| humidity | String | Current humidity percentage. |
| wind_speed | String | Wind speed in km/h or mph. |
| condition | String | Short description of the weather (e.g., "Sunny"). |
6. Error Codes
| Status Code | Message | Description |
|---|---|---|
| 401 | Unauthorized | Invalid or missing API key. |
| 404 | Not Found | City not found in the database. |
| 500 | Internal Server Error | Unexpected server-side issue. |
2 Documenting a User Management API
Exercise 2: Documenting a Currency Exchange API
Scenario: You are assigned to document the **Currency Exchange API**, which allows users to retrieve real-time currency exchange rates.
Your Task: Write an API reference document covering:
- Overview of the API.
- Endpoints and HTTP methods.
- Request parameters in a structured table.
- An example API request (including cURL).
- A sample response from the API.
- Response parameters in a structured table.
- Possible error codes and troubleshooting guidance.
- Rate limits and authentication details.
Provided API Code:
Below is a sample API request and response:
API Request:
GET https://api.currencyexchange.com/latest?base=USD&target=EUR&apikey=your_api_key
Sample Response:
{
"base_currency": "USD",
"target_currency": "EUR",
"exchange_rate": 0.85,
"last_updated": "2025-02-17T12:00:00Z"
}
Bonus Challenge: Explain rate limits and how developers should handle them.
Solution to Exercise 2
1. Overview
The **Currency Exchange API** allows developers to retrieve the latest currency exchange rates in real time. It supports multiple currency pairs and provides accurate conversion rates.
2. Endpoints and Methods
GET /latest – Retrieves the latest exchange rate between two currencies.
3. Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| base | String | Yes | None | The base currency (e.g., "USD"). |
| target | String | Yes | None | The target currency (e.g., "EUR"). |
| apikey | String | Yes | None | API key for authentication. |
4. Sample cURL Request
curl -X GET "https://api.currencyexchange.com/latest?base=USD&target=EUR&apikey=your_api_key" -H "Accept: application/json"
5. Sample Response
{
"base_currency": "USD",
"target_currency": "EUR",
"exchange_rate": 0.85,
"last_updated": "2025-02-17T12:00:00Z"
}
6. Response Parameters
| Parameter | Type | Description |
|---|---|---|
| base_currency | String | The base currency used in the conversion. |
| target_currency | String | The target currency. |
| exchange_rate | Float | The conversion rate from base to target currency. |
| last_updated | String | The timestamp when the exchange rate was last updated. |
7. Error Codes
| Status Code | Message | Description |
|---|---|---|
| 401 | Unauthorized | Invalid or missing API key. |
| 404 | Not Found | Invalid currency code. |
| 429 | Too Many Requests | Rate limit exceeded. |
3 Documenting an E-commerce Product API
Exercise 3: Documenting a Flight Status API
Scenario: You are assigned to document the **Flight Status API**, which allows users to retrieve real-time flight status based on flight number and date.
Your Task: Write an API reference document covering:
- Overview of the API.
- Endpoints and HTTP methods.
- Request parameters in a structured table.
- An example API request (including cURL).
- A sample response from the API.
- Response parameters in a structured table.
- Possible error codes and troubleshooting guidance.
Provided API Code:
Below is a sample API request and response:
API Request:
GET https://api.flightstatus.com/status?flight_number=AI302&date=2025-02-17&apikey=your_api_key
Sample Response:
{
"flight_number": "AI302",
"airline": "Air India",
"status": "On Time",
"departure": {
"airport": "Indira Gandhi International Airport (DEL)",
"scheduled_time": "2025-02-17T14:30:00Z"
},
"arrival": {
"airport": "Heathrow Airport (LHR)",
"scheduled_time": "2025-02-17T18:45:00Z"
}
}
Bonus Challenge: Explain how API users should handle delays or canceled flights.
Solution to Exercise 3
1. Overview
The **Flight Status API** provides real-time flight tracking and status updates. Developers can use this API to track flights, departure times, arrival times, and delay notifications.
2. Endpoints and Methods
GET /status – Retrieves the latest flight status.
3. Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| flight_number | String | Yes | None | Unique flight number (e.g., AI302). |
| date | String | Yes | None | The flight date (format: YYYY-MM-DD). |
| apikey | String | Yes | None | API key for authentication. |
4. Sample cURL Request
curl -X GET "https://api.flightstatus.com/status?flight_number=AI302&date=2025-02-17&apikey=your_api_key" -H "Accept: application/json"
5. Sample Response
{
"flight_number": "AI302",
"airline": "Air India",
"status": "On Time",
"departure": {
"airport": "Indira Gandhi International Airport (DEL)",
"scheduled_time": "2025-02-17T14:30:00Z"
},
"arrival": {
"airport": "Heathrow Airport (LHR)",
"scheduled_time": "2025-02-17T18:45:00Z"
}
}
6. Response Parameters
| Parameter | Type | Description |
|---|---|---|
| flight_number | String | Unique flight number. |
| airline | String | Airline name. |
| status | String | Flight status (e.g., "On Time", "Delayed"). |
7. Error Codes
| Status Code | Message | Description |
|---|---|---|
| 401 | Unauthorized | Invalid or missing API key. |
| 404 | Not Found | Flight not found for the given date. |
| 500 | Internal Server Error | Unexpected server-side issue. |
4 Documenting a Social Media API
Exercise 4: Documenting a Movie Database API
Scenario: You are assigned to document the **Movie Database API**, which allows users to search for movies by title, year, and genre.
Your Task: Write an API reference document covering:
- Overview of the API.
- Endpoints and HTTP methods.
- Request parameters in a structured table.
- An example API request (including cURL).
- A sample response from the API.
- Response parameters in a structured table.
- Pagination details.
- Possible error codes and troubleshooting guidance.
Provided API Code:
Below is a sample API request and response:
API Request:
GET https://api.moviedb.com/search?title=Inception&year=2010&genre=Sci-Fi&page=1&apikey=your_api_key
Sample Response:
{
"page": 1,
"total_results": 1,
"total_pages": 1,
"movies": [
{
"title": "Inception",
"year": 2010,
"genre": "Sci-Fi",
"director": "Christopher Nolan",
"actors": ["Leonardo DiCaprio", "Joseph Gordon-Levitt", "Ellen Page"],
"ratings": {
"IMDB": 8.8,
"Rotten Tomatoes": "87%"
}
}
]
}
Bonus Challenge: Explain how API users should handle pagination.
Solution to Exercise 4
1. Overview
The **Movie Database API** allows developers to search for movies based on various filters such as title, year, and genre. It returns a paginated list of results with detailed movie information.
2. Endpoints and Methods
GET /search – Retrieves a list of movies based on search parameters.
3. Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| title | String | No | None | Filters movies by title. |
| year | Integer | No | None | Filters movies by release year. |
| genre | String | No | None | Filters movies by genre (e.g., "Action", "Comedy"). |
| page | Integer | No | 1 | Specifies the results page number. |
| apikey | String | Yes | None | API key for authentication. |
4. Sample cURL Request
curl -X GET "https://api.moviedb.com/search?title=Inception&year=2010&genre=Sci-Fi&page=1&apikey=your_api_key" -H "Accept: application/json"
5. Sample Response
{
"page": 1,
"total_results": 1,
"total_pages": 1,
"movies": [
{
"title": "Inception",
"year": 2010,
"genre": "Sci-Fi",
"director": "Christopher Nolan",
"actors": ["Leonardo DiCaprio", "Joseph Gordon-Levitt", "Ellen Page"],
"ratings": {
"IMDB": 8.8,
"Rotten Tomatoes": "87%"
}
}
]
}
6. Pagination
The API supports pagination. Use the `page` parameter to retrieve additional results.
7. Error Codes
| Status Code | Message | Description |
|---|---|---|
| 401 | Unauthorized | Invalid or missing API key. |
| 404 | Not Found | No movies matched the search criteria. |
| 500 | Internal Server Error | Unexpected server-side issue. |
5 Documenting a Payment Processing API
Exercise 5: Documenting a Food Recipe API
Scenario: You are assigned to document the **Food Recipe API**, which allows users to search for recipes by ingredients, cuisine, and meal type.
Your Task: Write an API reference document covering:
- Overview of the API.
- Endpoints and HTTP methods.
- Request parameters in a structured table.
- An example API request (including cURL).
- A sample response from the API.
- Response parameters in a structured table.
- Pagination details.
- Possible error codes and troubleshooting guidance.
- Rate limits and caching best practices.
Provided API Code:
Below is a sample API request and response:
API Request:
GET https://api.foodrecipes.com/search?ingredients=tomato,cheese&cuisine=Italian&meal_type=dinner&page=1&apikey=your_api_key
Sample Response:
{
"page": 1,
"total_results": 2,
"total_pages": 1,
"recipes": [
{
"title": "Margherita Pizza",
"cuisine": "Italian",
"meal_type": "Dinner",
"ingredients": ["Tomato", "Cheese", "Basil", "Flour"],
"instructions": [
"Preheat oven to 220°C.",
"Spread tomato sauce on pizza base.",
"Add cheese and bake for 15 minutes."
],
"nutrition": {
"calories": 270,
"protein": "12g",
"fat": "8g",
"carbohydrates": "36g"
}
}
]
}
Bonus Challenge: Explain how API users should handle rate limits and caching.
Solution to Exercise 5
1. Overview
The **Food Recipe API** allows developers to search for recipes based on ingredients, cuisine, and meal type. It returns a paginated list of results with detailed recipe information, including ingredients, cooking instructions, and nutritional values.
2. Endpoints and Methods
GET /search – Retrieves a list of recipes based on search parameters.
3. Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| ingredients | String | No | None | Filters recipes by ingredients (comma-separated). |
| cuisine | String | No | None | Filters recipes by cuisine type (e.g., "Italian"). |
| meal_type | String | No | None | Filters recipes by meal type (e.g., "Dinner"). |
| page | Integer | No | 1 | Specifies the results page number. |
| apikey | String | Yes | None | API key for authentication. |
4. Sample cURL Request
curl -X GET "https://api.foodrecipes.com/search?ingredients=tomato,cheese&cuisine=Italian&meal_type=dinner&page=1&apikey=your_api_key" -H "Accept: application/json"
5. Rate Limits & Caching Best Practices
The API allows **60 requests per hour**. Developers should **cache recipe data** to reduce redundant API calls.
6. Error Codes
| Status Code | Message | Description |
|---|---|---|
| 401 | Unauthorized | Invalid or missing API key. |
| 404 | Not Found | No recipes matched the search criteria. |
| 429 | Too Many Requests | Rate limit exceeded. |
What’s Next?
After completing these beginner exercises, you’ll have a solid foundation in REST API documentation. You’ll be ready to tackle more advanced concepts in the next chapter, Key API Concepts, where we’ll explore important topics like rate limiting, authentication mechanisms, pagination, and error handling in greater depth.
Key Takeaways
- Learning API documentation requires hands-on practice with realistic scenarios
- Well-structured API documentation includes clear endpoint descriptions, parameter tables, examples, and error handling
- Using consistent formats for requests, responses, and parameters makes documentation more usable
- Including example requests with cURL commands helps developers understand how to use the API
- Documenting error responses thoroughly helps developers troubleshoot issues efficiently
API Documentation Resources
Expand your knowledge of API documentation with these resources.
External Resources
Tools & APIs
Found value in the course?
Your support fuels my work!
Have an issue?
Help improve the course by reporting an issue
