Endpoint documentation structure in Rest API - Mini Project: Build & Apply

Endpoint documentation structure

📖 Scenario: You are building a simple REST API for a bookstore. You want to create clear documentation for one of your API endpoints so that other developers can understand how to use it.

🎯 Goal: Create a structured documentation for a REST API endpoint that shows the HTTP method, URL path, description, request parameters, and example response.

📋 What You'll Learn

Create a dictionary called endpoint_doc with keys: method, path, description, parameters, and response_example

Set method to the HTTP method as a string

Set path to the URL path as a string

Set description to a short explanation string

Set parameters to a list of dictionaries, each with name, type, and required keys

Set response_example to a dictionary showing a sample JSON response

Print the endpoint_doc dictionary at the end

💡 Why This Matters

🌍 Real World

Clear API documentation helps developers understand how to use your web services correctly and quickly.

💼 Career

API documentation skills are essential for backend developers, API designers, and technical writers working with web services.

1

Create the basic endpoint documentation dictionary

Create a dictionary called endpoint_doc with keys method, path, and description. Set method to "GET", path to "/books", and description to "Retrieve a list of books".

Rest API

# Create the endpoint_doc dictionary with method, path, and description
# Your code here

Need a hint?

Use curly braces {} to create a dictionary and assign the keys and values exactly as instructed.

2

Add request parameters list

Add a key parameters to the endpoint_doc dictionary. Set it to a list with two dictionaries: first with name as "author", type as "string", and required as False; second with name as "year", type as "integer", and required as False.

Rest API

endpoint_doc = {
    "method": "GET",
    "path": "/books",
    "description": "Retrieve a list of books"
}
# Add the parameters key with the list of parameter dictionaries
# Your code here

Need a hint?

Remember that parameters is a list of dictionaries. Use square brackets [] for the list and curly braces {} for each dictionary.

3

Add example response dictionary

Add a key response_example to the endpoint_doc dictionary. Set it to a dictionary with a key books whose value is a list of two dictionaries. The first dictionary has id: 1, title: "The Great Gatsby", author: "F. Scott Fitzgerald". The second dictionary has id: 2, title: "1984", author: "George Orwell".

Rest API

endpoint_doc = {
    "method": "GET",
    "path": "/books",
    "description": "Retrieve a list of books",
    "parameters": [
        {"name": "author", "type": "string", "required": False},
        {"name": "year", "type": "integer", "required": False}
    ]
}
# Add the response_example key with the example response dictionary
# Your code here

Need a hint?

Use nested dictionaries and lists to represent the example JSON response structure.

4

Print the endpoint documentation

Write a print statement to display the endpoint_doc dictionary.

Rest API

endpoint_doc = {
    "method": "GET",
    "path": "/books",
    "description": "Retrieve a list of books",
    "parameters": [
        {"name": "author", "type": "string", "required": False},
        {"name": "year", "type": "integer", "required": False}
    ],
    "response_example": {
        "books": [
            {"id": 1, "title": "The Great Gatsby", "author": "F. Scott Fitzgerald"},
            {"id": 2, "title": "1984", "author": "George Orwell"}
        ]
    }
}
# Print the endpoint_doc dictionary
# Your code here

Need a hint?

Use print(endpoint_doc) to display the dictionary.