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.

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.

Learning By Doing
These exercises are designed to simulate real-world API documentation tasks. You'll apply everything you've learned about documenting endpoints, parameters, requests, and responses to practical scenarios that technical writers face daily.

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:

  1. A real-world scenario providing context for the documentation task
  2. Technical details about the API you need to document
  3. Specific requirements for what you need to include
  4. 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:

  1. Read through all requirements before starting each exercise
  2. Structure your documentation with clear headings and organization
  3. Use tables for parameters, response fields, and error codes
  4. Include examples that demonstrate real-world usage
  5. Focus on clarity by using concise, developer-friendly language
  6. 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

Previous: Mastering cURL for API Testing and Documentation Next: Intermediate REST API Documentation Exercises
Start your learning journey!
Course Progress 0%
0 of 0 pages completed

Found value in the course?

Your support fuels my work!

Buy Me A Coffee