Published in November 02, 2020

API-first Development

What is It and How Does It Work?

The internet is powered by computers that communicate with each other to-and-fro over the web. A vast majority of that communication uses an architecture type for data exchange called REST (REpresentational State Transfer) API.

API?

Application Programming Interface (API) is an approach for independent software to communicate with each other. How software talk (interface) with each other is known as an API. It is an independent software-to-software communication.

RESTful APIs

REpresentational State Transfer (REST) is standard for building APIs. It consists of patterns and structure that stands as a guideline for building APIs. APIs that are built following such structure and patterns are known as RESTful web services. REST architecture is generally preferred over the SOAP API architecture because of the benefit of less bandwidth over the web.

We’ll talk more about the REST architecture.

Why API?

Let say you’re building a web application that showcases all the schools in your country, including every detail about the school, like the road directions through a map service. Would you build a map system with the necessary algorithms from scratch? wait…you would? No, don’t do that. What you can do is request an API service like Google Maps to get the geolocation data for schools in a particular location and display them. Congratulations! You just save yourself from the stress of building a mapping system. All you did was outsource that feature to a different system to handle it. That’s one big reason why APIs were created — the ability to consume resource from an independent system.

A consuming software can also provide an API as service for another software or system to consume. The consuming software does not have to be related to the systems it consumes from. in fact, they are usually not related.

With the advent of “API-first” methodology as a standard for building modern software, especially on the web, the use of APIs has provided a “future-proof” and multifaceted way of building web applications.

“API-first”

This approach consists mainly of two parts — front-end and the back-end — that are separated from each other. The back-end only deals with the server and database and provides the API service for the front-end, or client to be able to access its data. The front-end then manages the presentation (the part users see) of that data.

The approach of separating, or dividing services into different parts is broadly known as Service-oriented architecture.

The downside of the API-first approach is that it requires some configurations here and there. With this in mind, you might say “Why worry then? It’s just unnecessary work.”

Although it is easier to build a web application using the traditional method where both the front-end are interwoven with the back-end and the whole application sits on a remote server that processes and sends back responses to the client. It is not ideal to build modern applications this way as you’ll see why:

Firstly, an application built using the API-first method can be consumed by any front-end that uses JavaScript. If you’re a developer then supporting multiple front-ends should get you excited. It doesn’t matter what happens to the front-end or which framework is being used, whether React, Angular, or Vue. The back-end almost always remains the same. No major rewrite required for it.

Secondly, data from back-end application built using the API-first approach can be used internally and externally. A mobile application can be powered by the back-end API and does not need a different backend built to handle the app. Also, such data can be used for an in-house application. All the developer needs to be concerned about is requesting and presenting the data gotten from the backend API.

thirdly, applications built using this approach are fast. Remember that the front-end is separated from the back-end, hence when a request is made to the server the pages will load almost instantly. This is because no “real” processing is taking place at the server. Even when dynamic data is generated, it doesn’t stop the pages from loading. The area on the page for showing that dynamic data can be handled by putting a CSS loader, this gives the user a sense of incoming data. It doesn’t hold back the rest of the page from loading as it would on a server that has to process everything before responding.

The fourth advantage is security. With an API-first approach, there is no way to exploit server code (remember the separation of front-end from back-end). This is because no credential or confidential data is stored on the client. This makes it difficult for the application to be hacked.

Web API (server side)

Before we go on from here, I must do a recap of how the internet works. This will ultimately give you a better understanding of web APIs and the API-first approach. Besides, a web API sits on top of the underlying architecture and protocols that make the web works. But first and foremost, what is a server-side web API?

A server-side web API is a programmatic interface consisting of one or more publicly exposed endpoint to a defined request-respond message system typically expressed in JSON or XML, which is exposed via the web — most commonly by means of HTTP-based web server.

-- Wikipedia

It is a suite of endpoints that exposes a certain part of a database. URLs are pointed to available endpoints to get the available underlying data through HTTP actions.

Now, let do some recap to better understand the above definition.

World Wide Web (WWW)

The WWW as we know it today was made possible in 1989. The web runs on Hypertext Transfer Protocol (HTTP) that allows for the movement of a text containing links over the internet. With this idea, documents could be shared over the internet. This brought the notion of web pages. This invention has become the ideal way of computer communication over the internet.

URL

The Uniform Resource Locator (URL) refer to the address of resource(website) on the internet.

Take for instance the address of this website where you’re reading this post. The address is https://www.romeopeter.com.

When a client (any internet-connected device) enters the address, a request is sent to the server hosting this website and the server sends back a response containing a copy of the website. The request and response process is done through HTTP.

TCP/IP

Transmission Control Protocol and Internet Protocol (TCP/IP) are communication mechanism that state how data should be transferred over the internet.

DNS

Domain Name Servers (DNS) translate domain name like “romeopeter.com” into IP address, the address is then used to send an HTTP message to a server to get a copy of the webpage, and the server sends it as a response. An IP address is a sequence of numerical character separated by a dot (.) that every internet-connected device has to have. It uniquely identifies the device. The reason behind DNS is because a website name like “romepeter.com” is easier to remember for humans than an address like 198.23.159.66

HTTP actions

HTTP actions, or verbs are a list of keyword that allows a client to retrieve and manipulate data on a server. These are knows has request methods. When a client sends an HTTP request to a server to get data, such request is a GET request.

The client can CREATE, READ, UPDATE, and DELETE data stored on the server. This is know as CRUD (Create-Read-Update-Delete) functionalities and web applications implement these functions.

For instance, every tweet you make or delete you set off one of the CRUD actions. The same thing applies to every data generated on the fly by a user.

The four most common HTTP request methods are GET, POST, PUT, and DELETE. These four methods account for the CRUD functionality.

Diagram
HTTP Actions                            CRUD Functions
------------                            --------------

GET ------------------------------->    Read
POST ------------------------------>    Create
PUT ------------------------------->    Update
DELETE ------------------------------>  Delete

You read content using the using GET action, create using POST, update using PUT and delete content using DELETE.

Status Code

When a client sends a request to a server, the server executes the requests and sends back a response with a status code. HTTP status codes are issued by a server in response to a client’s request.

The general category of status codes are:

  • 2xx Success - Request by client was understood and resolved
  • 3xx Redirection - Request moved or redirected
  • 4xx Client Error - Error in client request, usually bad URL request
  • 5xx Server Error - Server failed to process or resolve a request

For every HTTP request, there are only four potential outcomes: it worked (2xx), redirected to different URL (3xx), Error from the client (4xx), Error from the server (5xx).

The common ones are 200 (OK), 201 (created), 301 (moved permanently), 404 (Not Found), 500 (Server Error).

Statelessness

Every HTTP request-response circle happens independently or in complete isolation. This means no memory of previous request or response is stored and no request or response is affected by the previous one from the same client. This is known as statelessness.

When a client makes a request, it includes the necessary data needed for the server to fulfil or resolve that request. The server will not fulfil a new request using data from the previous one.

Although HTTP protocol is stateless (no memory), state (memory) is necessary for every traditional web application. When you login in a web application, a state is created on the server to identify you and every further request you make. For example, a state is created to manage your online shopping cart when you shop online.

We’ll learn more about states when we dive into API authentication.

REST

We talked earlier about REST (REpresentational State Transfer) being an architecture type for building an API. But what we didn’t talk about was the intention and features of RESTful APIs.

REST is a standard for building APIs for the web. The standard is consistent for building and consuming APIs via the the HTTP protocol.

Three main features of REST:

  • It is stateless
  • Supports HTTP action GET, POST, PUT, DELETE)
  • Return data in JSON (the preferred format) or XML.

API Authentication

API authentication is a scheme for user verification and identification.

In an API driven software, when a user makes a request (in the case where a user tries to log in) to the server, the server identifies the user firstly so further request from that user can be resolved. If the credentials match what the server has stored then the user is verified (authenticated), else a message with the appropriate HTTP status code will be sent as response to the client indicating that the user is not verified (unauthenticated).

API authentication is different from the simpler traditional web authentication where a session (state) is created for the verified user on the server. This way of authentication is quite straight forward because the session remembers who the authenticated entity until the state is terminated.

API authentication uses HTTP which is a stateless protocol. the protocol has no memory of the previous request-response cycle. That means there is no way to tell if a user authenticated or not because each request happens independently. To resolve the issue of authentication, a unique identifier is passed along with each HTTP request to the server.

There are so many ways you take to when implementing an API authentication. In this section we’ll look at the most common ones.

Basic Authentication

This is the most common approach(because of it simplicity) in implementing an API authentication. With this method, you pass in username and password separated by a colon (username:password) as value into a special HTTP header keyword called Authorization.

Diagram
{
    Authorization: Basic bGT06bJHG3yZQ7Niub9uy6bi5i
}

The username:password value is encoded in base64, which is an encoding technique to convert the value to 64 bit characters.

This method does not require cookies or session ID because it uses request header.

Once the request gets to the server, the server checks the Authorization header and compares the username:password value with credential it has stored. If the credentials match then the user is verified and the server fulfills the client request and response is sent (200 OK). If the user is not verified a message and status code (401 Unauthorized) is sent back to the client, informing that the authentication failed and therefore can not grant request.

Diagram
Client                                                                      Server
--------                                                                    --------

GET / HTTP/1.1
------------------------->
                                                            HTTP/1.1 401 Unauthorized
                                                                 WWW-Authenticate: Basic
                                                            <------------------------
GET / HTTP/1.1
Authorization: Basic bGT06bJHG3yZQ7Niub9uy6bi5i
------------------------------------------------->

                                                            HTTP/1.1 200 OK
                                                            <------------------------

The down side is that credentials must be sent to the server on every request. This is not secure and efficient.

Basic Authentication should only be used Over HTTPS, which is secured version of HTTP.

Session Authentication

API session-based authentication is a combination of Basic Authentication and Session Authentication.

To understand how this works, you have to understand how session-based cookie authentication works in tradition web application.

When a user sends a login request from a client to a server that utilizes session and cookie authentication scheme, the server resolves the request if credential (mostly username and password) match and a session ID (unique identifier) is returned as a response. The response is then stored as a cookie in the browser.

Session IDs are unique to each client (in this case the browser). The validity of the ID is only within the client. The ID can not be used across multiple domains.

The server creates a session object (state) containing information about a user, including the credentials.

Further requests from the client have to include the session ID as an HTTP request header. The server uses the session ID from the request header to identify the user by matching it with the session object that holds all related information of that user in the server. If there’s a match then the user is identified and the request is resolved.

Session ID is terminated by both server and client when user logs out. If the user logs in again, a new session ID is generated and stored as cookie in the browser.

The session and cookie approach are stateful because data is stored on the client and the server.

Now, back to API Session Authentication. In this case, the Session Authentication as stated above is implemented and Basic Authentication is used to send the session ID via HTTP request header for each request. The difference with this combination of authentication scheme is that the user is only authenticated once, unlike the single Basic Authentication (credentials are sent for each request). This makes it more secure and efficient as the server does not have to verify the user on each request, rather it only matches session ID with the session object on the server as a faster way of looking up the user.

Let see a simplified Illustration of how this works.

Diagram
Client                                                                      Server
------                                                                      ------

POST / HTTP/1.1
credential(username&password)
------------------------->
                                                            HTTP/1.1 200 OK
                                                       Set-cookie: sessionID = ksd...
                                                            <------------------------
GET / HTTP/1.1
Authorization: Basic ksd6kBSDKkjhds7KK2kjUGb9uyi
------------------------------------------------->

                                                            HTTP/1.1 200 OK
                                                            <------------------------

From the above diagram, a user logs in and the session ID is sent as a response to be stored as a cookie in the browser. Basic Authentication is then used to send the session ID via HTTP request header to the server. The server matches session ID with its session object and a confirmation (200 OK) is sent back to the client.

The downside of this approach of authentication is that it not capable of scaling. The use of session ID makes it limited to only one domain. This means it can not support multiple front-ends, like a website and mobile app. Also, this approach is difficult to maintain across servers as sessions object have to be maintained and kept up-to-date. And lastly, the cookie is sent for every request, whether needed or not, which is inefficient.

Session-based authentication scheme should not be used if the purpose of the API is to be used across multiple domains.

Bearer Authentication

Bearer authentication (or token authentication) is an authentication scheme that uses the exchange of token (cryptographic characters) to grant access to a user.

Bearer authentication means to “give access to the bearer of this token.” It is a stateless authentication scheme. The token is generated by the server and sent to the client to be stored as either a cookie or in local storage. The token is passed to the head of all future request going to the server. The server uses the token to verify that the user is authenticated. The server does not create a session (state). That means no record of the user is kept on the server, all it does is check if the token is valid.

Diagram
Client                                                                      Server
------                                                                      ------

POST / HTTP/1.1
------------------------->
                                                            HTTP/1.1 404 Unauthorized
                                                            <------------------------
GET / HTTP/1.1
Authorization: Bearer 401f7ac837da42b97f613d789819ff93537bee6a
------------------------------------------------->

                                                            HTTP/1.1 200 OK
                                                            <------------------------

This approach of authentication is not only the safest for most web APIs, it comes with major benefits too:
  • Scalability. There’s no need worrying about maintaining up-to-date session object, since token are only stored on the client.
  • The token can be shared across domains. Multiple front-end can be supported: building for both web and mobile.

Bearer authentication should only be used over HTTPS (Secured Hypertext Transfer Protocol).

Conclusion

We covered some core concept of an API-driven software. From what an API means, to a RESTful API, the API-first approach, the underlying technology of web APIs and the many different methods of HTTP authentication.

There are other methods of authentications we didn’t touch, like, JWT (JSON Web Token), API keys and OAuth 2.0.

I leave the rest (see what I did there? 😁) to you as a challenge to find out on your own.


Hi, my name is Romeo Peter. I'm a self-taught software developer and blogger --- I build web application, and automate business processes. I don't know it all, but what I do know, I manage to share for others to learn.

Follow me on Twitter. I share my thoughts there.

I'm available for work. Contact me to work on a project or work with you. I usually get back immediately.