How do APIs Work? A Beginner's Guide

#What is an API?

API stands for Application Programming Interface, when any two software components need to communicate with each other they can do so with the help of an API. APIs have their own set of predefined rules, protocols, and definitions based on which the communication takes place. All applications that we use in our day-to-day lives are in a way powered by APIs, they kind of form the backbone of communication.

For instance, when you search for a product on Amazon, the Amazon app on your phone communicates with the Amazon servers that will send back the list of items to show you. The app on your phone (client) will send a request to the Amazon backend servers, which will handle the request, gather appropriate data from a cache layer or a database server, prepare a response, and send it back to the client. For any API, the request and response formats will be defined earlier and documented for future reference. For instance, in the case of a “Search Product API”, the request needs to contain the keywords to search for, the identity of the user who is sending the request, and the response format could be an array of objects that will have certain key-value pairs based on which the client will display the product list.

It’s not only mobile apps or web-facing frontend apps that can be API clients for consuming data, even backend servers can be clients of other backend APIs. For example, an application’s backend API for registering a user can insert the user record in the database and then communicate to an email service via an API call for sending a confirmation email to the user. The application that is requesting the data is the client and the application that sends the response is the server.

#How do APIs work

All APIs have their own set of protocols and definitions, so each and every API type will have a different type of operating mechanism. There are different types of APIs like REST APIs, GraphQL, Websocket APIs, SOAP, RPC APIs, and more. We will discuss the most important ones currently in Software Engineering.

REST APIs

REST stands for REpresentational State Transfer. Rest APIs are very popular and for a long time, they were the de facto standard for developing backend APIs. They are used by everyone from enterprises to small-scale companies in their software projects.

The above image depicts the most common way developers implement REST APIs. The client can send requests with HTTP methods like:

• GET - retrieve data
• POST - create data
• PUT - replace data
• PATCH - partially modify data
• DELETE - remove data

Note that, depending on the API, some of these methods may not be available. Finally, the data to be exchanged can be in JSON or XML format (JSON is a popular default choice).

How a REST API works:

• A REST request is made up of the endpoint, HTTP method, Header, and Body.
• When a client requires a resource, it contacts the server via an API call. The endpoint URL and required parameters/headers/body of the request are agreed upon earlier.
• The server confirms if the client is authorized to make that API request and if so it proceeds ahead.
• The server processes the request, it can reach out to other services, databases, and caches to gather the required information, but the client will not be aware of how the server is fulfilling the request.
• The server sends a response to the client, which includes if the request was successful or not and the information requested.

For example, To get the list of products the client can hit GET /products API on the server with the authentication token of the user in the headers of the request and if the token is valid the server process the request and return an array of objects with all product information, there will be a common agreement between the client and server decided beforehand, this agreement is known as an API Contract.

If we were to send a request to themoviedb.org API to fetch the details of a particular movie, in Python, it would look like this:

import requests

api_url = "https://api.themoviedb.org/3/movie/"
movie_id = "400617"

response = requests.get(api_url + movie_id + "?api_key=" + API_KEY) # API_KEY defined behind the scenes

print(response.json())

The response would look like the following:

{
    "adult": false,
    "backdrop_path": "/vpRMzPqHC03I7hPPET4Av2OT8dI.jpg",
    "belongs_to_collection": null,
    "budget": 35000000,
    "genres": [
        {
            "id": 18,
            "name": "Drama"
        },
        {
            "id": 10749,
            "name": "Romance"
        }
    ],
    "homepage": "http://focusfeatures.com/phantom-thread",
    "id": 400617,
    "imdb_id": "tt5776858",
    "original_language": "en",
    "original_title": "Phantom Thread",
    "overview": "In 1950s London, renowned British dressmaker Reynolds Woodcock comes across Alma, a young, strong-willed woman, who soon becomes ever present in his life as his muse and lover.",
    "popularity": 16.068,
    "poster_path": "/hgoWjp9Sh0MI97eAMZCnIoVfgvq.jpg",
    "production_companies": [
        {
            "id": 178,
            "logo_path": null,
            "name": "Ghoulardi Film Company",
            "origin_country": "US"
        },
        {
            "id": 10146,
            "logo_path": "/xnFIOeq5cKw09kCWqV7foWDe4AA.png",
            "name": "Focus Features",
            "origin_country": "US"
        },
        {
            "id": 10338,
            "logo_path": "/el2ap6lvjcEDdbyJoB3oKiYgXu9.png",
            "name": "Perfect World Pictures",
            "origin_country": "CN"
        },
        {
            "id": 13184,
            "logo_path": "/pfUB1a62jSMIqp4Xmaq6z2cgW0B.png",
            "name": "Annapurna Pictures",
            "origin_country": "US"
        }
    ],
    "production_countries": [
        {
            "iso_3166_1": "US",
            "name": "United States of America"
        },
        {
            "iso_3166_1": "GB",
            "name": "United Kingdom"
        }
    ],
    "release_date": "2017-12-25",
    "revenue": 47756590,
    "runtime": 130,
    "spoken_languages": [
        {
            "english_name": "English",
            "iso_639_1": "en",
            "name": "English"
        },
        {
            "english_name": "French",
            "iso_639_1": "fr",
            "name": "Français"
        }
    ],
    "status": "Released",
    "tagline": "",
    "title": "Phantom Thread",
    "video": false,
    "vote_average": 7.297,
    "vote_count": 2938
}

The response structure is the way it is defined in the API and it will always be the same. If you would like to request additional information you would have to make a request to another endpoint. A Rest API is stateless, meaning that the server will not maintain any client-related information (state), and the client will have to identify itself on every request.

GraphQL API

As per GraphQL’s official website, “GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.” Those who are new to GraphQL please refer to this article for an in-depth introduction to GraphQL. In recent years, GraphQL is gaining traction quite aggressively and many enterprise companies are moving towards using GraphQL to support their use cases.

REST APIs were quite powerful and the default choice for API development for more than a decade, but with time some disadvantages started making a difference. Some of the disadvantages are

• All resources have a different endpoint
• Overfetching, Underfetching, N+1 Request problem
• High coupling between the client requirements and the backend APIs

GraphQL has only one endpoint, and the data you require is defined in the request itself. If you recall the example from the section above on REST APIs with themoviedb.org, GraphQL would help remove the unnecessary information and add something additional to the response with just one call only.

For example, if we were to require only a title, overview, or cover image that response would deliver too much information. In addition, if we were to add the director and performers for main roles, we would have to fetch the data from another endpoint. In GraphQL, this could look like this:

query getMovie($id: String!) {
      movies(where: { id: $id }) {
        title
        overview
        coverImage {
          url
        }
        director {
          name
        }
        performers {
          name
        }
      }
    }

GraphQL is a solution to all these problems and you can read more on GraphQL vs REST.

Hygraph is a GraphQL-native Federated Content Platform that provides developers with a powerful and extensible GraphQL API. We empower developers with a powerful query & mutation API that is ready to use within seconds. All you need to do is sign up with a free plan and configure your schema to get started.

WebSocket APIs

Rest APIs are quite popular when the use case is uni-directional communication. The client establishes a TCP connection, requests some data from the server, the server authenticates the client, processes the request, and sends back a response, then the TCP connection is closed. Next time, the client needs something, a fresh TCP connection will be established and the same process will be repeated. This approach works well when you need to show a list of products, search through them or show a product detail page, but it would be very terrible for user experience if used to build chat systems, where the expectations are of real-time communication.

Introducing WebSockets, their primary use case is to support superfast bi-directional communication, it is stateful in nature, works on a full-duplex model wherein both the client and server can send any number of requests back and forth and there will be a single TCP connection established at the very start. The everyday chat applications that we use like Slack, Whatsapp, and others rely heavily on WebSockets as their backbone.

Web APIs

When working with an application that will have access to a web browser, for instance, any frontend facing HTML, CSS, JavaScript / React / Vue / Angular, etc applications. You also have the superpower to use the large set of Web APIs exposed by the web browser.

When working with frontend web applications, developers often use HTML DOM API or use libraries that in turn use the HTML DOM API. It allows you to manipulate the HTML Document Object Model that is rendered by the browser on your screen. The DOM tree includes the elements such as <body> , <div> , and more. This API comes in handy when you want to dynamically make changes to the elements during runtime.

This HTML file has a script which has a function setBodyAttr, it is using document object to manipulate the background color of the body element on runtime in the browser.

#Example

Let us try to understand the working of APIs in general via a high-level example. Here is the architecture of a very simple Auth Service that exposes two APIs - register, and login and is capable of sending emails.

The components of this backend service include:

• Some client applications
• Backend web server
• Hygraph headless content platform
• An email service.

The client applications can be mobile or web applications, they will know the backend server’s URL and the backend server will be the only point of communication for them. Also, they will know the API endpoint and the request parameters for the login and register APIs exposed by the backend server. The client apps prepare the appropriate request payload and will make an API call to the Backend Server.

The backend server can either be a REST API server or a GraphQL server, it will have the business logic of the Register and Login API, validate the inputs received from the client apps, and interact with our Hygraph CMS to perform CRUD operations on the database. For example, for Register API, it will first need to check if a user with the same email already exists, for login API, it will need to validate the username and password, hence the backend server will need to communicate to Hygraph. While interacting with the Hygraph CMS, the backend server will act as a client and make API calls with GraphQL queries and mutations toHygraph which will in turn perform operations on the database.

After the above steps, the backend server will send email confirmations for which it will prepare the proper request payload as per the email service’s API contract and trigger an API call to the email service, the email service’s responsibility will be to send the confirmation emails to the users, and finally, the backend server will process and send final responses to the client as agreed in the API contract which must be defined at the very start.

Please note that this is a very simple auth service to understand “API calls” better, a real-life auth service will be much more complex and can have more layers, OAuth flows, job queues, and more.

#Benefits Of Using API

Integration & Developer Productivity

With APIs, you can integrate new applications with existing software systems. This increases development speed because you don’t have to write all of the functionality from scratch and you can reuse existing functionalities. Developers can focus more on the crux of the product instead of the other services which are generic and can be easily outsourced.

Costing

Many times, the cost of creating and maintaining a new service and its infrastructure from scratch at scale exceeds the cost of outsourcing it to a reliable giant who can do it right. Here the API integrations come in handy for cutting costs.

Maintenance

APIs act as gateways between two systems. When required the systems change their code internally ensuring they do not change the defined API contract, this way any future code changes from one party do not affect the others.

Improved value proposition

Applications can make themselves more appealing to customers by integrating APIs made available by well-known companies like Google, Amazon, etc.

#Conclusion

Overall, understanding the core concept of different APIs, their use case, protocols, and their operating mechanism is a must as they are the standard way of communication between applications and offer many benefits. Starting from base, we recommend getting your hands dirty on GraphQL and Rest APIs at the very least and then one can explore WebSockets.