Beginner REST API Documentation exercises | API Documentation - A step by step guide for technical writers

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 to Expect?

Whether you’re new to API documentation or looking to refine your skills, these exercises will help you bridge the gap between theory and real-world scenarios.

How It Works:
The chapter contains 5 hands-on exercises that simulate real-world API documentation tasks.

You’ll:

Get an API request (or part of it) and write the documentation.
Think through how to structure information clearly.
Compare your response with a provided solution.

The goal? Help you practice like you’re already working as an API technical writer.

Let’s Start with the Basics!

These beginner exercises will help you get comfortable with:

Understanding API requests & responses.
Documenting endpoints, parameters, and authentication.
Handling API errors and responses effectively.

Each exercise builds on the last—so by the end of this section, you’ll have solid experience documenting REST APIs.

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.

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.

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.

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.

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.

Ready? Click an exercise and start documenting!

Found value in the course? Your support fuels my work!

Course completed

37%

Have an issue? Please provide specific feedback by reporting an issue.