Application Programming Interfaces


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 πŸ“–


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.


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.


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 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'


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.


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)