**Unlocking the Power of APIs: A Data Scientist’s Essential Guide to API Documentation Mastery**

1. Introduction

Working across fields like statistics, programming, and AI demands the skill to clearly explain complex methods and findings. Knowing how APIs work is especially important for smooth teamwork and sharing ideas.

For one, it improves teamwork among members and stakeholders. Data Science (DS) projects usually involve a mix of experts—data specialists, developers, business analysts, project managers, and others. Clear APIs act as a common language that helps these varied groups understand and use DS models and tools properly.

Next, well-written API documentation makes it easier to reproduce results and helps new team members get up to speed. In DS, models and analyses must be tested and matched. Good API documentation lets others follow the same steps, use the same data, and get the same results. This is key for making decisions based on data.

Lastly, as Data Science plays a bigger role in business plans, clear APIs help data solutions scale and make working with data simpler. For example, APIs can be important for collecting data for projects, fast building and developing apps that need current data. By using APIs to gather data from sources like REST Countries (see Case 6.1), data scientists can spend more time on analysis instead of data collection.

In this post, we will:

• Give a quick look at what an API is and why it matters in software development.
• Review the main parts of the REST API.
• Explain the most common formats and show real examples of API calls and responses.
• Describe how good API documentation should be, with details on endpoints, parameters, and responses.

2. What is API

An API (Application Programming Interface) is a set of rules that lets different programs talk to each other and share data. Think of it as a go-between that helps apps, devices, servers, and systems swap information while keeping their inner workings hidden.

Picture a library full of books and a librarian who knows exactly where each book is. The librarian acts like an API, making it easy for readers (our “frontend”) to get the book they need without searching the whole catalog (our “backend”). If they want another book, they just ask the librarian again.

This example shows how an API connects users to data, providing quick and easy access to what they need.

A specific kind of API is the REST API, which follows the rules of REST (Representational State Transfer). REST APIs are popular in the industry since they are light, flexible, and use standard data formats like JSON or XML.

3. Components of REST API

Each REST API part plays an important role in organizing how clients and servers interact.

3.1. Resources

A resource is anything you can access through the API. Every resource has a unique address (URI), such as:

Here, images is a group of cat images from The Cat API website [1], and search?size=med is a filter to see only medium-sized images.

3.2. HTTP Methods

HTTP methods are ways to work with resources:

• GET — get data about a resource;
• POST — make a new resource;
• PUT — change a resource completely;
• PATCH — change part of a resource;
• DELETE — remove a resource.

3.3. Requests and Responses

Data goes back and forth between client and server using HTTP requests and responses. JSON is the usual format since it’s simple to read and works with most programming languages.

3.4. HTTP Headers

Headers carry extra details, like the type of content (Content-Type) or login info (Authorization).

3.5. HTTP Response Codes

Every HTTP request gets a response with a status code:

• 200 OK — request went well;
• 201 Created — resource made successfully;
• 400 Bad Request — problem with the request;
• 401 Unauthorized — no permission;
• 404 Not Found — resource doesn’t exist;
• 500 Internal Server Error — server issue.

4. API Clients

API clients like Postman or Bruno [2] make working with APIs easier by offering tools to send requests and manage responses. Instead of using command-line tools or writing code as shown in Case 6.1, these tools have visual features that speed up tasks.

In Case 6.2, we’ll use Bruno to work with the JokeAPI site [3]. Bruno makes it simpler to connect different software systems. Without Bruno or similar tools, developers would have to build each HTTP request by hand and handle raw responses themselves.

5. Tips on Creating Good API Documentation

Making clear API documentation is important so users can easily learn and use your API. Here are some key tips:

5.1. Keep It Simple, Clear, and Consistent

Skip technical terms and don’t mix up words. Use straightforward language that’s easy to understand. If needed, set up a style guide to keep everything the same. List the main rules you’ll follow.

5.2. Include Comprehensive Details

Effective API documentation should contain several key components. Specifically, a standard API method page should feature:

• A Brief Description – one to two sentences that clearly define the endpoint’s primary function.
• The Request Syntax

  – a summary of how to structure the API call.

• Authentication Methods – an explanation of the steps required to access the API securely.
• Parameters and Data Types: – a listing of the required parameters along with their expected data types for requests.
• Examples of Requests – sample requests, including both correct and error-based examples, to demonstrate effective API usage.

6. Practical Cases

Case 6.1: Querying a RESTful API with Python

Gathering country-level data is critical for analyzing global, regional, or national trends and supporting informed decisions by governments, businesses, and researchers. When working with country data from sources like the REST Countries website [4], developers can retrieve information about nations via a RESTful API to efficiently obtain area, population, and demonyms without manually scraping large volumes of web content. The following script fetches and displays data about countries in Central America:

import requests
import json

url = 'https://restcountries.com/v3.1/region/Central America/?fields=name,area,population,demonyms'
response = requests.get(url)
jdata = response.json()
formatted_json = json.dumps(jdata, indent=4)
print(formatted_json)

Geographic regions follow UN classification methodology [5]. You can also filter responses to include only specific fields [6]: in this example, those are name, area, population count, and demonyms.

The output is returned as a human-readable JSON file:

[
    {
        "name": {
            "common": "Honduras",
            "official": "Republic of Honduras",
            "nativeName": {
                "spa": {
                    "official": "República de Honduras",
                    "common": "Honduras"
                }
            }
        },
        "demonyms": {
            "eng": {
                "f": "Honduran",
                "m": "Honduran"
            },
            "fra": {
                "f": "Hondurienne",
                "m": "Hondurien"
            }
        },
        "area": 112492.0,
        "population": 9892632
    },
    {
        "name": {
            "common": "Costa Rica",
            "official": "Republic of Costa Rica",
            "nativeName": {
                "spa": {
                    "official": "República de Costa Rica",
                    "common": "Costa Rica"
                }
            }
        },
        "demonyms": {
            "eng": {
                "f": "Costa Rican",
                "m": "Costa Rican"
            },
            "fra": {
                "f": "Costaricaine",
                "m": "Costaricain"
            }
        },
        "area": 51100.0,
        "population": 5309625
    },
    {
        "name": {
            "common": "Guatemala",
            "official": "Republic of Guatemala",
            "nativeName": {
                "spa": {
                    "official": "República de Guatemala",
                    "common": "Guatemala"
                }
            }
        },
        "demonyms": {
            "eng": {
                "f": "Guatemalan",
                "m": "Guatemalan"
            },
            "fra": {
                "f": "Guatémaltèque",
                "m": "Guatémaltèque"
            }
        },
        "area": 108889.0,
        "population": 18079810
    },
    {
        "name": {
            "common": "Panama",
            "official": "Republic of Panama",
            "nativeName": {
                "spa": {
                    "official": "República de Panamá",
                    "common": "Panamá"
                }
            }
        },
        "demonyms": {
            "eng": {
                "f": "Panamanian",
                "m": "Panamanian"
            },
            "fra": {
                "f": "Panaméenne",
                "m": "Panaméen"
            }
        },
        "area": 75417.0,
        "population": 4064780
    },
    {
        "name": {
            "common": "Nicaragua",
            "official": "Republic of Nicaragua",
            "nativeName": {
                "spa": {
                    "official": "República de Nicaragua",
                    "common": "Nicaragua"
                }
            }
        },
        "demonyms": {
            "eng": {
                "f": "Nicaraguan",
                "m": "Nicaraguan"
            },
            "fra": {
                "f": "Nicaraguayenne",
                "m": "Nicaraguayen"
            }
        },
        "area": 130373.0,
        "population": 6803886
    },
    {
        "name": {
            "common": "Belize",
            "official": "Belize",
            "nativeName": {
                "bjz": {
                    "official": "Belize",
                    "common": "Belize"
                },
                "eng": {
                    "official": "Belize",
                    "common": "Belize"
                },
                "spa": {
                    "official": "Belice",
                    "common": "Belice"
                }
            }
        },
        "demonyms": {
            "eng": {
                "f": "Belizean",
                "m": "Belizean"
            },
            "fra": {
                "f": "Bélizienne",
                "m": "Bélizien"
            }
        },
        "area": 22966.0,
        "population": 417634
    },
    {
        "name": {
            "common": "El Salvador",
            "official": "Republic of El Salvador",
            "nativeName": {
                "spa": {
                    "official": "República de El Salvador",
                    "common": "El Salvador"
                }
            }
        },
        "demonyms": {
            "eng": {
                "f": "Salvadoran",
                "m": "Salvadoran"
            },
            "fra": {
                "f": "Salvadorienne",
                "m": "Salvadorien"
            }
        },
        "area": 21041.0,
        "population": 6029976
    }
]

Case 6.2: Making a Request to JokeAPI Using Bruno

JokeAPI is a free, open-source REST API that delivers jokes in multiple formats, including JSON, XML, YAML, or plain text [3].

1. Open Bruno and navigate to Collections → + Create collection.
2. Assign a name to your collection, such as Sample API.
3. The new collection appears in the left panel. To add a request, click … → New Request.
4. Choose the request type (HTTP) and give it a name, for example, joke_request.
5. In the URL field, select the method (GET) and enter the endpoint.

Your documentation—such as how to format code snippets, snapshots, the preferred tone of voice, and similar guidelines—shapes the consistency and clarity of the final output.

1. The URL was built according to your chosen preferences on the JokeAPI website. In our example, we selected any joke category, excluding NSFW, religious, political, racist, and sexist content (these were flagged and added to the blacklist).
2. The parameters we picked on the website and copied show up in the request after the ? as a query string appended to the endpoint URL in the GET field, with each one separated by &. These same parameters will also be displayed in a table under the Params tab.
3. Hit Send, give it a moment… and you’ll receive a decent joke in return (“The generation of random numbers is too important to be left to chance.”). Take note of the request status — it shows 200 OK, meaning everything went through successfully.

One important detail: in this example, we didn’t need an API key to reach our REST API resource. If we did, we’d have to include it as a header in a separate Headers tab.

Case 6.3: Sending a request to NASA Open APIs using an API key

NASA’s APOD (Astronomy Picture of the Day) is a widely used service that gives users access to a daily astronomy-related photo or video, along with a description [7].

Let’s walk through a quick example based on the NASA APOD API documentation, following the tips outlined in the 5th paragraph.

NASA APOD API Documentation

Description: This API lets you fetch images or videos for specific dates, date ranges, or randomly selected entries from the APOD NASA website.

Request Syntax: GET

Authentication Methods: To use the APOD API, you need to include an API key in your request. You can get a free API key by signing up at . This key must be passed as a query parameter in the request.

Parameters and Data Types: refer to the table below

* — required parameters

Request Examples

Valid request returning 200 OK

GET ?api_key=<your_api_key/>

{
    "copyright": "Simone Curzi",
    "date": "2026-05-18",
    "explanation": "Spiral galaxy NGC 3169 appears to be coming apart like a ball of cosmic yarn. Located roughly 70 million light-years away, south of the bright star Regulus in the faint constellation Sextans. Its tightly wound spiral arms are being stretched into sweeping tidal tails as NGC 3169 (left) and its neighbor NGC 3166 pull on each other gravitationally. Over time, the two galaxies will merge into one — a common destiny even for bright galaxies in our local universe. Stretched-out stellar arcs and plumes are telltale signs of the ongoing gravitational dance captured in this deep, colorful image of the galaxy group. The telescopic frame covers about 20 arc minutes, or roughly 400,000 light-years at the group's estimated distance, and includes the smaller, bluish NGC 3165 on the right. NGC 3169 is also known to emit across the spectrum from radio waves to X-rays, hosting an active galactic nucleus powered by a supermassive black hole.",
    "hdurl": "
    "media_type": "image",
    "service_version": "v1",
    "title": "Unraveling NGC 3169",
    "url": "
}

Valid request returning 200 OK for a date range

GET ?start_date=2025-03-03&end_date=2025-03-05&api_key=<your_api_key/>

[
    {
        "date": "2025-03-03",
        "explanation": "There's a new lander on the Moon. Yesterday, Firefly Aerospace's Blue Ghost achieved the first-ever successful commercial lunar landing. Over its planned 60-day mission, Blue Ghost will deploy several NASA-commissioned scientific instruments, including PlanetVac, which collects lunar dust by creating a small whirlwind of gas. Blue Ghost will also carry the telescope LEXI, which captures X-ray images of Earth's magnetosphere. LEXI's data should help scientists better understand how Earth's magnetic field shields the planet from solar wind and flares. In the photo, the shadow of the Blue Ghost lander is visible on the cratered lunar surface, while the glowing orb of Earth hangs just above the horizon. Upcoming robotic Blue Ghost missions aim to support lunar astronauts as part of NASA's Artemis program, with Artemis III currently slated to return humans to the Moon in 2027.",
        "hdurl": "
        "media_type": "image",
        "service_version": "v1",
        "title": "Blue Ghost on the Moon",
        "url": "
    },
    {
        "copyright": "Valerio Minato",
        "date": "2025-03-04",
        "explanation": "Why does this Moon look so unusual? A major reason is its striking red color. The hue results from blue light being scattered by Earth's atmosphere — the same phenomenon that makes the daytime sky look blue. The Moon also appears oddly distorted. Its peculiar shape is an optical effect caused by layers in Earth's atmosphere that bend light differently due to abrupt changes in temperature or pressure. A third factor is that, purely by chance, an airplane happens to be passing in front of it. The featured picturesque gibbous Moon was photographed about two weeks ago above Turin, Italy. Our familiar celestial companion was part of a rare quadruple alignment that also featured two historic landmarks: the Sacra di San Michele on the nearby hill and the Basilica of Superga in the distance. Your Sky Surprise: What image did APOD feature on your friend's birthday? (post 1995)",
        "hdurl": "
        "media_type": "image",
        "service_version": "v1",
        "title": "A Quadruple Alignment over Italy",
        "url": "
    },
    {
        "copyright": "Todd Anderson",

        "date": "2025-03-05",
        "explanation": "On the right, in blue, sits the Pleiades. A common legend tells that one of the cluster's brighter stars has faded since it was named. On the left, glowing in crimson, is the California Nebula. Named for its distinctive shape, the California Nebula is significantly dimmer, making it harder to spot. Also cataloged as NGC 1499, this cloud of red glowing hydrogen sits roughly 1,500 light years from Earth. Although around 25 full moons could fit between them, the featured wide-angle, deep field composite image has captured both. A close look at the deep image will also show the star-forming region IC 348 and the molecular cloud LBN 777 (the Baby Eagle Nebula).    Jump Around the Universe: Random APOD Generator",
        "hdurl": "
        "media_type": "image",
        "service_version": "v1",
        "title": "Seven Sisters versus California",
        "url": "
    }
]

Error request with 400 Bad Request status

GET ?date=2023-03-01&end_date=2023-03-01&api_key=

{
    "code": 400,
    "msg": "Bad Request: invalid field combination passed. Allowed request fields for apod method are 'concept_tags', 'date', 'hd', 'count', 'start_date', 'end_date', 'thumbs'",
    "service_version": "v1"
}

7. Conclusion

Learning to read (and maybe even write) API documentation goes beyond a simple technical task; it’s an essential part of effective data analytics, aiding collaboration, reproducibility, adoption, and scalability. When data scientists place a high value on clear, detailed documentation, they can confidently engage with contemporary tools.

For example, many data scientists now work with tools such as Claude Code, a coding AI agent. With Claude Code, files stay on your local computer, and the AI assistant pulls them from there and forwards the text to the Anthropic API for processing. It’s important to note that thorough documentation for the Claude API outlines every detail of its behavior. Specifically, the Claude API is a RESTful API at offering programmatic access to Claude models and managed Claude agents [8]. Hopefully, after finishing this post, you’ll have a clearer understanding of this (and other) documentation 🙂

Thank you for reading!

List of References

1. The Cat API web page:
2. Bruno documentation:
3. JokeAPI web page:
4. REST countries v3.1:
5. UNSD Methodology: Standard country or area codes for statistical use (M49)
6. List of fields on GitLab page of the project:
7. NASA Open APIs:
8. Claude API Docs — An Overview: