Past the Mannequin: Why Information Scientists Should Embrace APIs and API Documentation

1. Introduction

on the intersection of assorted domains — statistics, programming, AI — the power to convey complicated methodologies and insights turns into essential. Thus, a talent to cope with complete API ideas is important for efficient communication throughout the crew.

First, it fosters collaboration amongst crew members and stakeholders. Information Science (DS) tasks usually contain multidisciplinary groups consisting of not solely information specialists, but in addition software program builders, enterprise analysts, mission managers, and so forth. Properly-documented APIs function a bridge between all of them, enabling these various teams to grasp and make the most of DS fashions and instruments appropriately.

Second, high-quality API documentation enhances reproducibility and may scale back on boarding time for newcomers. In DS, the place fashions and analyses have to be validated and replicated, clear API documentation ensures that others can comply with the identical processes, use the identical information, and obtain constant outcomes. That is notably essential in creating data-driven decision-making.

Lastly, as Information Science turns into more and more built-in into enterprise methods, well-documented APIs can enhance the scalability of information options and simplify the method of working with information. For instance, APIs can play a major function in information gathering for tasks, enabling fast prototyping and growth of purposes that depend on up-to-date data. By leveraging APIs for information gathering from sources like REST International locations (see Case 6.1), information scientists can give attention to evaluation relatively than information acquisition.

On this put up we’ll:

Briefly discover what an API is and its function in software program growth.
Meet with the principle parts of the REST API.
Describe the commonest codecs and supply sensible instances of API calls and responses.
Sum up how API documentation ought to look, with data on endpoints, parameters, and responses.

2. What’s API

An API (Software Programming Interface) includes a set of strategies by which completely different packages talk with one another and trade information. Primarily, it’s an middleman that enables purposes, gadgets, servers, and different programs to trade data, whereas hiding the processes inside every system from one another.

Think about a library with a big assortment of books, and the librarian who is aware of the place to search out the precise e-book a sure reader wants. Right here we will referred the librarian as an API that simplifies the method of accessing data, saving readers (our “frontend”) from losing time looking out via your complete e-book catalog (our “backend”), permitting to focus solely on their particular request. Moreover, if readers want one other books, they’ll repeat the method of sending request to API once more.

Picture generated by Writer utilizing NightCafé

This analogy highlights the function of the API as an middleman between the consumer and the information supply, offering handy and environment friendly entry to data.

A particular case of API is a REST API which follows the ideas of the REST (REpresentational State Switch) structure. REST APIs are named the business commonplace as a result of they’re light-weight, versatile, and use frequent information codecs like JSON or XML.

3. Elements of REST API

Every of the REST API parts under performs an important function in organizing client-server interactions.

3.1. Assets

A useful resource is any entity that may be accessed via the API. Every useful resource has a novel identifier (URI), for instance:

https://api.thecatapi.com/v1/photos/search?dimension=med

Right here, photos is a group of cats’ photos from The Cat API net web page [1], and search?dimension=med is the filter to view solely medium-sized photos.

3.2. HTTP Strategies

HTTP strategies are used to work together with sources:

GET — retrieve information a couple of useful resource;
POST — create a brand new useful resource;
PUT — replace a useful resource;
PATCH — partial replace a useful resource;
DELETE — delete a useful resource.

3.3. Requests and Responses

Information is exchanged between the shopper and server through HTTP requests and responses. Usually, the JSON format is used as a result of it’s simple to learn and supported by the overwhelming majority of programming languages.

3.4. HTTP Headers

Headers are used to convey extra data, such because the content material sort (Content material-Kind) or authentication parameters (Authorization).

3.5. HTTP Response Codes

Every HTTP request receives a response with a selected standing code:

200 OK — profitable request;
201 Created — useful resource efficiently created;
400 Dangerous Request — shopper request error;
401 Unauthorized — lack of entry rights;
404 Not Discovered — useful resource not discovered;
500 Inner Server Error — server-side error.

4. API Purchasers

API purchasers like Postman or Bruno [2] simplify API interplay by offering a devoted workspace for sending requests and managing responses. As an alternative of utilizing command-line instruments or writing code as we did in Case 6.1, these brokers provide visible interfaces and automation options that pace up workflows.

Thus, in Case 6.2, we’ll think about using Bruno to work together with the JokeAPI net web page [3]. Utilizing Bruno simplifies the complicated technique of interplay between completely different software program programs. With out Bruno and different API purchasers, builders must manually assemble every HTTP request and course of every uncooked response from scratch.

5. Tips about Creating Good API Documentation

Creating efficient API documentation is essential for guaranteeing that customers can simply perceive and make the most of your API. Listed here are some key ideas to bear in mind:

5.1. Prioritize Simplicity, Readability, and Consistency

Keep away from technical jargon and inconsistent terminology. As an alternative, use simple and easy sufficient language that’s simple to comply with. If vital, set up a mode information to take care of uniformity all through your documentation. Right here you’ll be able to state the principle guidelines which are used all through your documentation, e.g. the way to format the code snippets, snapshots, the popular tone of voice, and so forth.

5.2. Embody Complete Particulars

Thorough API documentation ought to embody a number of important parts, particularly a typical web page with API technique consists of:

A Transient Description (1-2 sentences) which clearly define the principle function of the endpoint.
The Request Syntax: An outline of API name.
Authentication Strategies: Element the authentication processes wanted to entry the API securely.
Parameters and Information Varieties: Specify the required parameters and their corresponding information varieties for requests.
Examples of Requests: Present examples of right request and request with error for instance the way to use the API successfully.

6. Sensible Circumstances

Case 6.1: Make a request to a RESTful API utilizing Python

Gathering country-level information is important for understanding international, regional, or nationwide tendencies, enabling knowledgeable decision-making for governments, companies, and particular person researchers. When working with nation information just like the REST International locations web site [4], information scientists can get details about nations through a RESTful API to fetch space, inhabitants, and demonyms effectively with out manually scraping tons of net information. The code under retrieves and shows information about nations in Central America:

import requests
import json

url = 'https://restcountries.com/v3.1/subregion/Central America/?fields=title,space,inhabitants,demonyms'
response = requests.get(url)
jdata = response.json()
formatted_json = json.dumps(jdata, indent=4)
print(formatted_json)

Geographic areas are outlined utilizing UN methodology [5]. You too can filter response on sure fields [6]: in our case, these are title, space, quantity of inhabitants, and demonyms.

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

[
    {
        "name": {
            "common": "Honduras",
            "official": "Republic of Honduras",
            "nativeName": {
                "spa": {
                    "official": "Repu00fablica 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": "Repu00fablica 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": "Repu00fablica de Guatemala",
                    "common": "Guatemala"
                }
            }
        },
        "demonyms": {
            "eng": {
                "f": "Guatemalan",
                "m": "Guatemalan"
            },
            "fra": {
                "f": "Guatu00e9maltu00e8que",
                "m": "Guatu00e9maltu00e8que"
            }
        },
        "area": 108889.0,
        "population": 18079810
    },
    {
        "name": {
            "common": "Panama",
            "official": "Republic of Panama",
            "nativeName": {
                "spa": {
                    "official": "Repu00fablica de Panamu00e1",
                    "common": "Panamu00e1"
                }
            }
        },
        "demonyms": {
            "eng": {
                "f": "Panamanian",
                "m": "Panamanian"
            },
            "fra": {
                "f": "Panamu00e9enne",
                "m": "Panamu00e9en"
            }
        },
        "area": 75417.0,
        "population": 4064780
    },
    {
        "name": {
            "common": "Nicaragua",
            "official": "Republic of Nicaragua",
            "nativeName": {
                "spa": {
                    "official": "Repu00fablica 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": "Bu00e9lizienne",
                "m": "Bu00e9lizien"
            }
        },
        "area": 22966.0,
        "population": 417634
    },
    {
        "name": {
            "common": "El Salvador",
            "official": "Republic of El Salvador",
            "nativeName": {
                "spa": {
                    "official": "Repu00fablica 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: Make a request to JokeAPI utilizing Bruno

JokeAPI is a free, open-source REST API that delivers jokes in numerous codecs, e.g. JSON, XML, YAML, or plain textual content [3].

Open Bruno and choose Collections → + Create assortment.
Choose a reputation on your assortment, e.g. Pattern API.
The created assortment is displayed within the left panel. To create a request, click on … → New Request.
Choose the request sort (HTTP) and specify its title e.g. joke_request.
Within the URL cell, choose the strategy (GET) and enter the endpoint https://v2.jokeapi.dev/joke/Any?blacklistFlags=spiritual,political,racist,sexist&sort=single.
The URL had been constructed based mostly on preferences you chose on JokeAPI web site. In our instance, we selected any joke class, besides nsfw, spiritual, political, racist and sexist ones (they have been flagged and put to the blacklist).
The parameters that we chosen on the web site and copied appeared within the request after the ? as a question string to the endpoint URL within the GET discipline, separated by & from one another . They may also seem in a desk within the Params tab.
Click on Ship, wait a bit … and also you’ll get a not-that-bad joke in response (“The technology of random numbers is simply too essential to be left to likelihood.”). Take note of the standing of out request – it’s 200 OK which suggests success.

How Bruno interface appears to be like like. Screenshot made by Writer.

It’s essential to notice that on this instance, we didn’t require an API key to entry our REST API useful resource. In any other case, we must go it as a header in a separate Headers tab.

Case 6.3: Make a request to NASA Open APIs with API key

The APOD (Astronomy Image of the Day) of NASA is a well-liked service which offers customers with entry to the every day photograph or video associated to astronomy, together with an outline [7].

Let’s briefly make an instance of NASA APOD API documentation pattern based mostly on the guidelines from the fifth paragraph.

NASA APOD API Documentation

Description: This API permits customers to retrieve photos or video for particular dates, ranges, or simply randomly chosen ones from the APOD NASA web site.

Request Syntax: GET https://api.nasa.gov/planetary/apod

Authentication Strategies: To entry the APOD API, it is best to embody an API key in your request. To get a free API key, you’ll want to sigh up at https://api.nasa.gov/. This key must be included as a question parameter within the request.

Parameters and Information Varieties: see the desk under

Parameter	Kind	Description
api_key*	string	Your private NASA API key. If not specified, one could use `DEMO_KEY` to examine how requests appear to be
date	string (datetime)	The date of the APOD picture to retrieve. If not specified, defaults as in the present day
start_date	string (datetime)	The beginning of the date vary for retrieving photos. Can’t be utilized in one request with `date`
end_date	string (datetime)	The top of the date vary for retrieving photos. Utilizing with `start_date` in the identical request
rely	integer	Returns a selected variety of randomly chosen photos. Don’t use with datetime parameters
thumbs	boolean	Returns the URL of the video thumbnail, if `true`. In a case if the APOD object just isn’t a video, this parameter is ignored

* — required parameters

Examples of Request

Right Request with 200 OK standing

GET https://api.nasa.gov/planetary/apod?api_key=

{
    "copyright": "Simone Curzi",
    "date": "2026-05-18",
    "rationalization": "Spiral galaxy NGC 3169 appears to be like to be unraveling like a ball of cosmic yarn. It lies some 70 million light-years away, south of vibrant star Regulus towards the faint constellation Sextans. Wound up spiral arms are pulled out into sweeping tidal tails as NGC 3169 (left) and neighboring NGC 3166 work together gravitationally. Finally the galaxies will merge into one, a standard destiny even for vibrant galaxies within the native universe. Drawn out stellar arcs and plumes are clear indications of the continued gravitational interactions throughout the deep and colourful galaxy group photograph. The telescopic body spans about 20 arc minutes or about 400,000 light-years on the group's estimated distance, and consists of smaller, bluish NGC 3165 to the precise. NGC 3169 can also be identified to shine throughout the spectrum from radio to X-rays, harboring an lively galactic nucleus that's the website of a supermassive black gap.",
    "hdurl": "https://apod.nasa.gov/apod/picture/2605/ngc3169_ngc3166_ngc3165.jpg",
    "media_type": "picture",
    "service_version": "v1",
    "title": "Unraveling NGC 3169",
    "url": "https://apod.nasa.gov/apod/picture/2605/ngc3169_ngc3166_ngc3165px1024.jpg"
}

Right Request with 200 OK standing for a variety of dates

GET https://api.nasa.gov/planetary/apod?start_date=2025-03-03&end_date=2025-03-05&api_key=

[
    {
        "date": "2025-03-03",
        "explanation": "There's a new lander on the Moon. Yesterday Firefly Aerospace's Blue Ghost executed the first-ever successful commercial lunar landing. During its planned 60-day mission, Blue Ghost will deploy several NASA-commissioned scientific instruments, including PlanetVac which captures lunar dust after creating a small whirlwind of gas. Blue Ghost will also host the telescope LEXI that captures X-ray images of the Earth's magnetosphere. LEXI data should enable a better understanding of how Earth's magnetic field protects the Earth from the Sun's wind and flares.  Pictured, the shadow of the Blue Ghost lander is visible on the cratered lunar surface, while the glowing orb of the planet Earth hovers just over the horizon. Goals for future robotic Blue Ghost landers include supporting lunar astronauts in NASA's Artemis program, with Artemis III currently scheduled to land humans back on the Moon in 2027.",
        "hdurl": "https://apod.nasa.gov/apod/image/2503/BlueGhostShadow_Firefly_4096.jpg",
        "media_type": "image",
        "service_version": "v1",
        "title": "Blue Ghost on the Moon",
        "url": "https://apod.nasa.gov/apod/image/2503/BlueGhostShadow_Firefly_960.jpg"
    },
    {
        "copyright": "Valerio Minato",
        "date": "2025-03-04",
        "explanation": "Why does this Moon look so unusual?  A key reason is its vivid red color. The color is caused by the deflection of blue light by Earth's atmosphere -- the same reason that the daytime sky appears blue.  The Moon also appears unusually distorted.  Its strange structuring is an optical effect arising from layers in the Earth's atmosphere that refract light differently due to sudden differences in temperature or pressure.  A third reason the Moon looks so unusual is that there is, by chance, an airplane flying in front. The featured picturesque gibbous Moon was captured about two weeks ago above Turin, Italy. Our familiar hovering sky orb was part of an unusual quadruple alignment that included two historic ground structures: the Sacra di San Michele on the near hill and Basilica of Superga just beyond.   Your Sky Surprise: What picture did APOD feature on your friend's birthday? (post 1995)",
        "hdurl": "https://apod.nasa.gov/apod/image/2503/QuadMoon_Minato_960.jpg",
        "media_type": "image",
        "service_version": "v1",
        "title": "A Quadruple Alignment over Italy",
        "url": "https://apod.nasa.gov/apod/image/2503/QuadMoon_Minato_960.jpg"
    },
    {
        "copyright": "Todd Anderson",
        "date": "2025-03-05",
        "explanation": "On the right, dressed in blue, is the Pleiades.  Also known as the Seven Sisters and M45, the Pleiades is one of the brightest and most easily visible open clusters on the sky. The Pleiades contains over 3,000 stars, is about 400 light years away, and only 13 light years across. Surrounding the stars is a spectacular blue reflection nebula made of fine dust.  A common legend is that one of the brighter stars faded since the cluster was named. On the left, shining in red, is the California Nebula.  Named for its shape, the California Nebula is much dimmer and hence harder to see than the Pleiades.  Also known as NGC 1499, this mass of red glowing hydrogen gas is about 1,500 light years away. Although about 25 full moons could fit between them, the featured wide angle, deep field image composite has captured them both.  A careful inspection of the deep image will also reveal the star forming region IC 348 and the molecular cloud LBN 777 (the Baby Eagle Nebula).    Jump Around the Universe: Random APOD Generator",
        "hdurl": "https://apod.nasa.gov/apod/image/2503/California2Pleiades_Anderson_9953.jpg",
        "media_type": "image",
        "service_version": "v1",
        "title": "Seven Sisters versus California",
        "url": "https://apod.nasa.gov/apod/image/2503/California2Pleiades_Anderson_960.jpg"
    }
]

Error Request with 400 Dangerous Request standing

GET https://api.nasa.gov/planetary/apod?date=2023-03-01&end_date=2023-03-01&api_key=

{
    "code": 400,
    "msg": "Dangerous Request: invalid discipline mixture handed. Allowed request fields for apod technique are 'concept_tags', 'date', 'hd', 'rely', 'start_date', 'end_date', 'thumbs'",
    "service_version": "v1"
}

7. Conclusion

Understanding the way to learn (and maybe write) API documentation isn’t just a technical activity; it’s a important part of profitable information analytics apply, enhancing collaboration, reproducibility, adoption, and scalability. By prioritizing clear and detailed documentation, information scientists can guarantee they are going to be snug working with trendy instruments.

For instance, many information scientists now use instruments like Claude Code, a coding AI agent. With Claude Code, your information are saved domestically in your laptop, and the AI assistant reads them from there and sends the textual content content material to the Anthropic API for processing. It’s value noting that complete documentation for the Claude API describes all of the nuances of its operation. Particularly, the Claude API is a RESTful API at https://api.anthropic.com that gives programmatic entry to Claude fashions and managed Claude brokers [8]. Hopefully, after studying this put up you’ll perceive this (and different) documentation a bit higher 🙂

Thanks for studying!