Past the Mannequin: Why Information Scientists Must Undertake APIs and API Documentation

1. Introduction

On the intersection of various disciplines similar to statistics, programming, and AI, advanced methodologies and the flexibility to speak insights are necessary. Subsequently, expertise in dealing with complete API ideas are important for efficient communication inside a workforce.

First, it fosters collaboration between workforce members and stakeholders. Information science (DS) initiatives usually contain multidisciplinary groups that embrace information specialists, in addition to software program builders, enterprise analysts, challenge managers, and extra. A well-documented API acts as a bridge between all of them, permitting these various teams to correctly perceive and make the most of DS fashions and instruments.

Second, high-quality API documentation can enhance reproducibility and scale back adoption time for newcomers. As a result of DS requires fashions and analyzes to be validated and replicated, clear API documentation ensures that others can observe the identical course of, use the identical information, and obtain constant outcomes. That is particularly necessary when making data-driven selections.

Lastly, as information science turns into more and more built-in into enterprise technique, well-documented APIs make information options extra extensible and simplify the processes of working with information. For instance, APIs play a key function in challenge information assortment, enabling fast prototyping and growth of purposes that depend on up-to-date data. By leveraging APIs to gather information from sources similar to REST international locations (see Case 6.1), information scientists can concentrate on evaluation fairly than information acquisition.

On this publish we’ll:

• A short clarification of what an API is and its goal in software program growth.
• Describes the primary elements of the REST API.
• It describes the most typical codecs and supplies sensible examples of API calls and responses.
• Summarize what good API documentation ought to appear like, together with details about endpoints, parameters, and responses.

2. What’s API?

An API (Software Programming Interface) consists of a set of strategies that enable totally different packages to speak with one another and alternate information. Primarily, it’s an middleman that enables purposes, units, servers, and different methods to alternate data, hiding the processes inside every system from one another.

Think about a library with an enormous assortment of books and a librarian who is aware of the place to seek out the precise ebook a selected reader wants. Right here, librarians may be known as APIs that simplify the method of accessing data, saving readers (the “entrance finish”) wasted time looking by means of your entire ebook catalog (the “again finish”), and permitting them to focus solely on their particular requests. Moreover, if the reader desires one other ebook, they’ll repeat the method by sending a request to the API once more.

This analogy emphasizes the function of APIs as intermediaries between customers and information sources, offering handy and environment friendly entry to data.

A particular case of APIs are REST APIs, which observe the idea of the REpresentational State Switch (REST) ​​structure. REST APIs are known as trade requirements as a result of they’re light-weight, versatile, and use widespread information codecs similar to JSON and XML.

3. REST API Parts

Every of the next REST API elements performs an necessary function in organizing the client-server interplay.

3.1.Assets

A useful resource is any entity that may be accessed by means of an API. Every useful resource has a singular identifier (URI). For instance:

https://api.thecatapi.com/v1/images/search?size=med

right here, photographs A set of cat photographs from The Cat API net web page. [1]and search?dimension=med This filter shows solely medium-sized photographs.

3.2. HTTP strategies

HTTP strategies are used to work together with assets.

• GET — Get information a couple of useful resource.
• POST — Create a brand new useful resource.
• PUT — Replace a useful resource.
• PATCH — Replace the useful resource partially.
• DELETE — Delete a useful resource.

3.3.Request and response

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

3.4. HTTP headers

The header is 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 — The request was profitable.
• 201 Created — The useful resource was created efficiently.
• 400 Unhealthy Request — Consumer request error.
• 401 Unauthorized — Lack of entry rights.
• 404 Not Discovered — Useful resource not discovered.
• 500 Inner Server Error — Server-side error.

4. API Consumer

API shoppers similar to Postman and Bruno [2] Simplify API interplay by offering a devoted workspace for sending requests and managing responses. As a substitute of utilizing command-line instruments or writing code as we did in Case 6.1, these brokers present a visible interface and automation capabilities that velocity up your workflow.

Subsequently, in Case 6.2, we think about using Bruno to work together with a JokeAPI net web page. [3]. Bruno simplifies advanced interplay processes between totally different software program methods. With out Bruno or different API shoppers, builders must manually assemble every HTTP request and course of every uncooked response from scratch.

5. Suggestions for writing nice API documentation

Creating efficient API documentation is necessary to creating it straightforward for customers to know and use your API. Listed below are some necessary ideas to bear in mind.

5.1. Prioritize simplicity, readability, and consistency

Keep away from jargon and inconsistent terminology. As a substitute, use easy, easy language that’s straightforward to know. If vital, set up a method information to take care of uniformity all through the doc. Right here you possibly can write the primary guidelines that will likely be used all through the doc, similar to tips on how to format code snippets, snapshots, and your most well-liked tone.

5.2. Embrace complete particulars

Thorough API documentation ought to embrace a number of key parts. Particularly, widespread pages containing API strategies embrace:

• transient clarification (1-2 sentences) Clearly clarify the first goal of the endpoint.
• Request syntax: Abstract of API calls.
• Authentication methodology: Particulars the authentication course of required to securely entry the API.
• Parameters and information sorts: Specify the parameters required for the request and their corresponding information sorts.
• Request instance: Supplies examples of right and inaccurate requests as an instance tips on how to use the API successfully.

6. Precise case

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

Accumulating country-level information is crucial for understanding world, regional, or nationwide traits, enabling governments, companies, and particular person researchers to make knowledgeable selections. REST Nations When working with nation information similar to web sites [4]information scientists can retrieve details about international locations by means of a RESTful API to effectively retrieve space, inhabitants, and demon names with out manually scraping giant quantities of net information. The code beneath retrieves and shows information about Central American international locations.

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 United Nations methodology [5]. You can too filter responses by particular fields [6]: In our case these are title, space, inhabitants quantity and demon title.

The output is offered 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: Utilizing Bruno to ship a request to JokeAPI

JokeAPI is a free, open-source REST API that delivers jokes in quite a lot of codecs together with JSON, XML, YAML, and plain textual content. [3].

1. Open Bruno and choose assortment → + Create a group.
2. Choose a reputation to your assortment. instance: Pattern API.
3. The created assortment will likely be displayed within the left panel. To create a request, … → new request.
4. Choose the kind of request (HTTP), specify its title. instance: joke_request.
5. in URL Choose the strategy within the cell (get hold of) Enter the endpoint https://v2.jokeapi.dev/joke/Any?blacklistFlags=Religion, Politics, Racism, Sexism&type=single.
   The URL was constructed primarily based on the settings you chose on the JokeAPI web site. On this instance, we chosen any joke class besides nsfw, spiritual, political, racist, and sexist (these had been flagged and blacklisted).
6. The parameters you chose and copied on the web site are ? As a question string to the endpoint URL GET fields separated by & From one another. These additionally seem within the desk beneath. parameters tab.
7. click on shipwait a minute…and you will get a not-so-bad joke (“Random quantity era is simply too necessary to depart to likelihood.”). Notice the standing of the out request. 200 OK means success.

It is necessary to notice that this instance didn’t require an API key to entry the REST API assets. In any other case it ought to be handed as a separate header. header tab.

Case 6.3: Ship a request to NASA Open API utilizing an API key

of apod NASA’s (Astronomy Image of the Day) is a well-liked service that enables customers to entry every day astronomy-related images and movies with descriptions. [7].

Let’s shortly create a pattern NASA APOD API documentation instance primarily based on the information within the fifth paragraph.

NASA APOD API documentation

clarification: This API permits customers to retrieve photographs and movies from a selected date, vary, or randomly chosen from the APOD NASA web site.

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

Authentication methodology: To entry the APOD API, you could embrace your API key in your request. To acquire a free API key, it’s good to go to the next web site: https://api.nasa.gov/. This key should be included as a question parameter in your request.

Parameters and information sorts: See desk beneath

parameters	sort	clarification
API_key*	string	Private NASA API key. If not specified, you should utilize it like this: DEMO_KEY To see what your request appears like
date	String (date and time)	Date of APOD picture to retrieve. If not specified, defaults to as we speak
begin date	String (date and time)	The beginning date of the date vary to retrieve photographs from. Can’t be utilized in one request date
finish date	String (date and time)	The top of the date vary for which you need to retrieve photographs. use collectively start_date throughout the identical request
depend	integer	Returns a sure variety of randomly chosen photographs. Don’t use with datetime parameters
thumb	boolean worth	Returns the video thumbnail URL. true. This parameter is ignored if the APOD object isn’t a video.

* — required parameter

Request instance

Appropriate request with 200 OK standing

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

{
    "copyright": "Simone Curzi",
    "date": "2026-05-18",
    "clarification": "Spiral galaxy NGC 3169 appears to be unraveling like a ball of cosmic yarn. It lies some 70 million light-years away, south of brilliant 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. Ultimately the galaxies will merge into one, a standard destiny even for brilliant galaxies within the native universe. Drawn out stellar arcs and plumes are clear indications of the continuing 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 appropriate. NGC 3169 can be recognized to shine throughout the spectrum from radio to X-rays, harboring an lively galactic nucleus that's the web site 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"
}

Appropriate request with 200 OK standing for date vary

GET https://api.nasa.gov/planetary/apod?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 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 Unhealthy Request standing

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

{
    "code": 400,
    "msg": "Unhealthy Request: invalid subject mixture handed. Allowed request fields for apod methodology are 'concept_tags', 'date', 'hd', 'depend', 'start_date', 'end_date', 'thumbs'",
    "service_version": "v1"
}

7. Conclusion

Realizing tips on how to learn (and typically write) API documentation isn’t just a technical activity. It is a key aspect for profitable information analytics practices, growing collaboration, reproducibility, adoption, and scalability. By prioritizing clear and detailed documentation, information scientists will likely be comfy utilizing fashionable instruments.

For instance, many information scientists now use instruments like Claude Code, a coding AI agent. With Claude Code, recordsdata are saved domestically in your laptop and an AI assistant reads them from there and sends the textual content content material to the Anthropic API for processing. Notice that the Claude API’s complete documentation explains each nuance of its operation. Particularly, the Claude API is a RESTful API that: https://api.anthropic.com Supplies programmatic entry to cloud fashions and managed cloud brokers. [8]. I hope you perceive this (and different) paperwork just a little higher after studying this publish:

Thanks for studying!

Reference record

1. Cat API net web page: https://thecatapi.com/
2. Bruno’s documentation: https://docs.usebruno.com/introduction/getting-started
3. JokeAPI net web page: https://jokeapi.dev/
4. REST Nation v3.1: https://restcountries.com/
5. UNSD methodology: Standard country or area code for statistics (M49)
6. Record of fields on the challenge’s GitLab web page: https://gitlab.com/restcountries/restcountries/-/blob/master/FIELDS.md
7. NASA Open API: https://api.nasa.gov/
8. Claude API documentation — overview: https://platform.claude.com/docs/en/api/overview