Application Programming Interfaces

introductiontowebapplications

Application Programming Interfaces (APIs) are used to create a layer of abstraction called "interface" between clients and services.

A few services commonly interfaced by APIs:

  • 🪺 a database
  • 💵 a bank payment service
  • 💬 a social media platform
  • 🗺️ a geolocation and mapping service
  • ...

An API can interface both internal and external services, e.g. developed by the company or another company.

For testing, you can use the fake jsonplaceholder API 🚀.

For the client of the API

  • 😎 Simplify the integration of a service
  • 💐 Standardized way to interact with a service
  • 🍹 The service is maintained by the provider (less work to do)

For the provider of the API

  • ✨ Can be used by websites, mobile apps, etc.
  • 🍹 Centralize (mostly database) accesses (ex: easier to find+patch bugs)
  • 💎 Can aggregate multiple data sources (i.g. multiple databases...)

📖 Terminology 📖

Endpoints

A few common terms:

  • Base endpoint: the base URL for any request to the API
  • Endpoint: a URL with one route of the API
  • Path: the part after the base endpoint

For the endpoint http://localhost:3000/users/1, the base endpoint would be http://localhost:3000 while the path would be /users/1.


HTTP requests

We can interact with an API from our browser, as our browser will send the HTTP request for us. Outside a browser, we create one manually.

Methods

An endpoint may allow multiple HTTP methods (GET, POST, PUT...). Refer to each API documentation to know which ones are available. See the HTTP protocol/method for your own API if needed.


Responses

Usually, only one format is supported, but developers may allow the developer to select a format (ex: header content-type)

➡️ Common formats are JSON 💫 or XML

➡️ See also: HTTP response code (200, 201, 400, 401, 403, 404, 500).

API Architectures

The Representational State Transfer (REST) API is the most common API architecture. It adheres to the following principles:

  • Statelessness 🙌: each request is self-sufficient. The server doesn't need to store additional external information.
  • Uniform 🛣️: consistent way of getting resources, such as using URI paths and HTTP methods to manipulate resources.
  • Cacheability 🐈: when possible resources must be cached. The server must communicate the caching rules (ex: request headers).
  • Client-server 🎫: both the client and the server should be independent of each other.

The format of the answers is often either JSON or XML.

It has a few disadvantages, such as the lack of standardization, or the over-fetching and under-fetching problems.

An alternative to rest is the SOAP (Simple Object Access Protocol) APIs. The request is made in XML through an HTTP request, and the response is also in XML.

SOAP is mainly used when sharing, often complex, structured data. The main disadvantage is that it's harder to learn.

Query an API

Each API often has what we call a wrapper or driver per programming language. Often, it is a library defining functions that we will call and that will handle the API HTTP request for us.

➡️ Ex: PHP GitHub API to use GitHub API in PHP.

If there is no wrapper or we want to make some tests, we can query the API ourselves, by sending HTTP requests.


cURL

cURL is a command that is useful for quick tests.

# postman generated command
$ curl --location --request POST 'URL' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'key=value'
# simplified command
$ curl -X POST 'URL' -d 'key=value' -H 'Content-Type: application/x-www-form-urlencoded'

Others

Postman Software

PostMan is a popular tool to test an API. Once downloaded,

  • Go to the collection tab
  • Create a new collection
  • Add a request
    • Click on "GET" to select the method
    • Fill the URL with an endpoint of the API
    • You can add
      • Query parameters (GET, tab Params)
      • Headers (tab Headers)
      • Body (POST, x-www-form-encoded, tab Body)
  • Then, click on send

➡️ Instead of editing your request to test another endpoint. Save it (CTRL+S/save button), and create a new one.

➡️ In the right-side panel, there is a code tag. Click on it, and you will be able to generate the API request in many languages.

Random

API Documentation

A few tools/platforms you may use 📚:

See also: OpenAPI tools.

API Reference

Search for APIs on rapidapi 🚀.

👻 To-do 👻

Stuff that I found, but never read/used yet.

  • insomnia
  • httpie
  • OData (Open Data)
  • WSDL (Web Services Description Language)