1. Introduction
on the intersection of varied domains — statistics, programming, AI — the flexibility to convey advanced methodologies and insights turns into essential. Thus, a talent to take care of complete API ideas is important for efficient communication throughout the workforce.
First, it fosters collaboration amongst workforce members and stakeholders. Information Science (DS) initiatives typically contain multidisciplinary groups consisting of not solely information specialists, but in addition software program builders, enterprise analysts, undertaking managers, and many others. Nicely-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 would possibly cut back on boarding time for newcomers. In DS, the place fashions and analyses should be validated and replicated, clear API documentation ensures that others can observe the identical processes, use the identical information, and obtain constant outcomes. That is significantly necessary in growing 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 position in information gathering for initiatives, enabling fast prototyping and improvement 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 deal with evaluation somewhat than information acquisition.
On this put up we are going to:
- Briefly discover what an API is and its objective in software program improvement.
- Meet with the primary parts of the REST API.
- Describe the commonest codecs and supply sensible instances of API calls and responses.
- Sum up how a superb 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. Basically, it’s an middleman that enables purposes, gadgets, servers, and different techniques 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 guide a sure reader wants. Right here we are able to referred the librarian as an API that simplifies the method of accessing data, saving readers (our “frontend”) from losing time looking via your entire guide 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.
This analogy highlights the position of the API as an middleman between the person and the info 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 trade normal as a result of they’re light-weight, versatile, and use widespread information codecs like JSON or XML.
3. Elements of REST API
Every of the REST API parts beneath performs an important position 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/photographs/search?dimension=med
Right here, photographs is a group of cats’ photographs from The Cat API internet web page [1], and search?dimension=med is the filter to view solely medium-sized photographs.
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 by way of HTTP requests and responses. Usually, the JSON format is used as a result of it’s straightforward to learn and supported by the overwhelming majority of programming languages.
3.4. HTTP Headers
Headers are used to convey further 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 particular standing code:
- 200 OK — profitable request;
- 201 Created — useful resource efficiently created;
- 400 Unhealthy Request — shopper request error;
- 401 Unauthorized — lack of entry rights;
- 404 Not Discovered — useful resource not discovered;
- 500 Inside Server Error — server-side error.
4. API Shoppers
API shoppers 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 supply visible interfaces and automation options that velocity up workflows.
Thus, in Case 6.2, we are going to think about using Bruno to work together with the JokeAPI internet web page [3]. Utilizing Bruno simplifies the advanced means of interplay between completely different software program techniques. With out Bruno and different API shoppers, 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 making certain 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 easy and easy sufficient language that’s straightforward to observe. If crucial, set up a mode information to take care of uniformity all through your documentation. Right here you may state the primary guidelines which are used all through your documentation, e.g. learn how to format the code snippets, snapshots, the popular tone of voice, and many others.
5.2. Embody Complete Particulars
Thorough API documentation ought to embody a number of important parts, specifically a typical web page with API technique contains:
- A Transient Description (1-2 sentences) which clearly define the primary objective of the endpoint.
- The Request Syntax: An summary of API name.
- Authentication Strategies: Element the authentication processes wanted to entry the API securely.
- Parameters and Information Sorts: Specify the required parameters and their corresponding information sorts for requests.
- Examples of Requests: Present examples of right request and request with error for instance learn how to use the API successfully.
6. Sensible Instances
Case 6.1: Make a request to a RESTful API utilizing Python
Gathering country-level information is important for understanding world, regional, or nationwide developments, 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 by way of a RESTful API to fetch space, inhabitants, and demonyms effectively with out manually scraping tons of internet information. The code beneath retrieves and shows information about nations in Central America:
import requests
import json
url = 'https://restcountries.com/v3.1/subregion/Central America/?fields=identify,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]. It’s also possible to filter response on sure fields [6]: in our case, these are identify, 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 identify e.g. joke_request.
- Within the URL cell, choose the strategy (GET) and enter the endpoint https://v2.jokeapi.dev/joke/Any?blacklistFlags=non secular,political,racist,sexist&sort=single.
The URL had been constructed primarily based on preferences you chose on JokeAPI web site. In our instance, we selected any joke class, besides nsfw, non secular, political, racist and sexist ones (they had 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 theGETarea, separated by&from one another . They may even 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 era of random numbers is simply too necessary to be left to likelihood.”). Take note of the standing of out request – it’s 200 OK which suggests success.
It’s necessary 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 picture or video associated to astronomy, together with an outline [7].
Let’s briefly make an instance of NASA APOD API documentation pattern primarily based on the guidelines from the fifth paragraph.
NASA APOD API Documentation
Description: This API permits customers to retrieve photographs 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’s best to embrace an API key in your request. To get a free API key, it is advisable to sigh up at https://api.nasa.gov/. This key needs to be included as a question parameter within the request.
Parameters and Information Sorts: see the desk beneath
| Parameter | Kind | Description |
| api_key* | string | Your private NASA API key. If not specified, one might use DEMO_KEY to test how requests seem like |
| date | string (datetime) | The date of the APOD picture to retrieve. If not specified, defaults as right now |
| start_date | string (datetime) | The beginning of the date vary for retrieving photographs. Can’t be utilized in one request with date |
| end_date | string (datetime) | The tip of the date vary for retrieving photographs. Utilizing with start_date in the identical request |
| depend | integer | Returns a selected variety of randomly chosen photographs. Don’t use with datetime parameters |
| thumbs | boolean | Returns the URL of the video thumbnail, if true. In a case if the APOD object shouldn’t be a video, this parameter is ignored |
* — required parameters
Examples of Request
Appropriate Request with 200 OK standing
GET https://api.nasa.gov/planetary/apod?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 vivid 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 typical destiny even for vivid 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 picture. The telescopic body spans about 20 arc minutes or about 400,000 light-years on the group's estimated distance, and contains smaller, bluish NGC 3165 to the suitable. NGC 3169 can also be identified to shine throughout the spectrum from radio to X-rays, harboring an energetic 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 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 Unhealthy Request standing
GET https://api.nasa.gov/planetary/apod?date=2023-03-01&end_date=2023-03-01&api_key=
{
"code": 400,
"msg": "Unhealthy Request: invalid area mixture handed. Allowed request fields for apod technique are 'concept_tags', 'date', 'hd', 'depend', 'start_date', 'end_date', 'thumbs'",
"service_version": "v1"
}7. Conclusion
Realizing learn how to learn (and maybe write) API documentation is not only a technical activity; it’s a important element of profitable information analytics follow, enhancing collaboration, reproducibility, adoption, and scalability. By prioritizing clear and detailed documentation, information scientists can guarantee they are going to be comfy 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 regionally in your pc, 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!
Checklist of References
- The Cat API internet web page: https://thecatapi.com/
- Bruno documentation: https://docs.usebruno.com/introduction/getting-started
- JokeAPI internet web page: https://jokeapi.dev/
- REST nations v3.1: https://restcountries.com/
- UNSD Methodology: Customary nation or space codes for statistical use (M49)
- Checklist of fields on GitLab web page of the undertaking: https://gitlab.com/restcountries/restcountries/-/blob/grasp/FIELDS.md
- NASA Open APIs: https://api.nasa.gov/
- Claude API Docs — An Overview: https://platform.claude.com/docs/en/api/overview
