API 101: What Is an API

An Application Programming Interface (API) is a set of services, tools, functions and protocols implemented in a piece of software and made available to other systems through a contract. Its documentation defines that contract and how to send structured requests, which determines how the application will respond. APIs abstract away the complexity of the system, simplifying the interaction between different pieces of software and letting applications communicate efficiently and in a standardized way.

Connection types

A client that wants to access the resources an API provides sends a request to an endpoint, following the format defined in the API’s documentation. After receiving the request, the API processes the information and returns the requested data to the client in the format established in the contract.

Some connection formats:

Web client and server:- Communication between a client and a web server.

• Based on HTTP requests.
• Usually used to carry data in JSON or XML format.

REST (Representational State Transfer):- Communication based on HTTP standards.

• Uses HTTP methods such as GET, POST, PUT and DELETE.
• Uses URIs to identify resources.

Remote Procedure Call (RPC):- Lets a piece of software request resources located on another machine on the network.

• Uses a specific syntax to request those resources.
• Can use different communication protocols, such as HTTP, TCP, UDP and others.

Application and local resource:- Communication between different parts of the same application or system.

• Usually done by calling functions within the same application.
• Can be synchronous or asynchronous, depending on the application’s architecture.

The difference between REST and RESTful

Although they’re sometimes used interchangeably without causing trouble, there is a distinction between the two terms. REST is an architecture that defines a set of principles for building web services, while RESTful refers to the implementation of those principles. REST lays out the general principles, such as the use of HTTP methods, and RESTful describes an implementation that follows the criteria REST established.

How an API works

You interact with an API by making requests to it. Here is a Python example using the requests library against an imaginary API with data from the game Dark Souls.

import requests
# API URL and GET request
url = "https://darksoulsbossesapi.com/api/bosses"
response = requests.get(url)

# Checking whether the request succeeded (status code 200)
if response.status_code == 200:
    # Extracting the data from the response
    bosses_data = response.json()
    # Printing the names of the Dark Souls bosses
    print("List of Dark Souls bosses:")
    for boss in bosses_data:
        print(boss['name'])
else:
    print("Error accessing the API:", response.status_code)

This example could return a JSON like:

[
 {
 "id": 1,
 "name": "Asylum Demon",
 "description": "The first boss of the game."
 },
 {
 "id": 2,
 "name": "Bell Gargoyles",
 "description": "A pair of gargoyles that guard the bell in the Undead Parish."
 },
 {
 "id": 3,
 "name": "Capra Demon",
 "description": "A boss found in the Lower Undead Burg."
 },
 …
]

Notes on API development

Developing an API means thinking about what it will abstract and the logic that will be used in its implementations and calls. A well-designed API should provide controlled access to a system through the endpoints defined in the contract, guaranteeing security and data integrity. It should be independent of the underlying system, meaning it should stay functional and consistent even when the system it supports changes. An API can be simple or complex, never confusing.

#python#apis