Introduction

Application Programming Interfaces (APIs) have radically changed how software applications interact. They have been instrumental in software development because, quite literally, different systems can now talk to each other. Reflecting both technological and software development practice changes, the way APIs are designed and consumed today has greatly changed over the last decades.

This tutorial covers the evolution of APIs, including the Pre-REST era, the rise of REST, REST alternatives, and the broader uses of APIs beyond simple data fetching.

What is API?

API is an acronym for Application Programming Interface. It is a set of procedures, practices, and methods employed in the construction of software. The APIs specify how the software components are required to behave; therefore, they offer communication between various applications.

APIs can be defined as a specific type of contract between various software entities. They describe the kind of calls a source software can make to the target software and the kind of data that can be interchanged. At the bottom, they strip out all the implementation and present only what a developer requires.

Most modern APIs, such as Google Maps API or Spotify API, need API keys for authentication and authorization. In most cases, the API keys works as an identifier, enabling some developers to request the API while the service provider monitors and polices its use.

What is a REST API?

REST stands for Representational State Transfer. It is an application program interface that is resource, addressable, client-server, stateless, cacheable, uniformly connected, layered system, and one with an architecture for networked applications. A REST API or RESTful API is an application program interface that is conforming to the architectural style of REST; this will be defined by:

• Stateless: Each request from the client to the server side must contain all information to understand this request.
• Client-Server: The client and the server should be separate and capable of growing independently.
• Cacheable: Responses to requests must specify whether they are cacheable.
• Uniform Interface: An appropriate and consistent manner of communicating with a particular server irrespective of the gadget or nature of the program.
• Layered System: A client cannot normally distinguish between being connected directly to the end server and being connected to an intermediary.
• Code on Demand (optional): Servers may temporarily provide a client with extra or changed functionality by transferring executable code.

REST APIs explicitly leverage HTTP methods like GET, POST, PUT, DELETE, etc., and model access to resources (nouns) rather than actions (verbs). Many popular APIs, including the Google Maps API, Chatgpt API, and Spotify API, follow REST principles.

Below is an example of what a Chatgpt API REST API request looks like:

1
2
3
4
5
6
7
8
9
GET /api/completions HTTP/1.1
Host: api.openai.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "model": "gpt-3.5-turbo",
  "messages": [{"role": "user", "content": "Hello, ChatGPT!"}]
}

Pre-REST Era (mid-1940s-2000)

In the earlier stages of computing, interfaces were quite simple, mostly limited only to hardware-level interaction and low-level machine code instructions. Inter-system communication was hardly established directly by manipulating the hardware components.

First generations of computers, such as ENIAC, a breakthrough in 1945, were physically rewired and used punch cards for programming. In the following enhancements, because technology evolved, came assembly languages that provided a higher degree of abstraction but were still far from the independence of the architecture of the hardware beneath.

In the 1950s and 1960s, higher-level programming languages like FORTRAN and COBOL further started to bridge the gap from human-readable code to machine instructions. However, the systems were still very hard to talk to each other; the communication was proprietary to a few protocols and custom-built interfaces.

RPC and SOAP

As distributed computing gained traction, more sophisticated methods of inter-system communication emerged:

Remote Procedure Call (RPC):

• Developed in the 1980s at Xerox PARC by Birrell and Nelson
• Made it possible for programs to run procedures on remote systems as if they were making local calls.
• It abstracted the complication of communication over a network and made distributed computing much more accessible.
• Implementations included Sun RPC, later ONC RPC, and DCE/RPC.
• These included tight coupling between the client and the server and problems with firewalls and heterogeneous environments.

Simple Object Access Protocol (SOAP): - First introduced at the end of the 1990s, originally developed by Microsoft - It is the XML-based protocol for structured information exchange in web services. - Platform-independent solution to operate over variable transport protocols—HTTP, SMTP, etc. - It provided broad security features through WS-Security and transactional capabilities through WS-AtomicTransaction. - Defined a standard way to define service interfaces WSDL - Web Services Description Language - Challenges included the verbose XML format, leading to larger payload sizes and potential performance problems.

These technologies laid the groundwork for more modern API architectures, addressing the growing need for standardized, interoperable communication between disparate systems in an increasingly connected digital landscape.

SOAP API

SOAP is a short form of Simple Object Access Protocol. It is a protocol for web services utilized in the structured exchange of information. It introduced the use of XML for messages as a format, but it doesn't rely on transport to negotiate and transmit messages. The characteristic features of SOAP APIs include:

• Message formatting in XML format
• Platform and language independence
• Supports stateful operations
• Inbuilt error handling
• Can support transport protocols like HTTP, SMTP, TCP, etc.

SOAP APIs are typically used in enterprise environments where a formal contract is needed between services or some complex and stateful operation that needs to be done. Below is an example of what a SOAP API request looks like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
POST /StockQuote HTTP/1.1
Host: www.example.org
Content-Type: application/soap+xml; charset=utf-8
Content-Length: nnn

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Header>
  </soap:Header>
  <soap:Body>
    <m:GetStockPrice xmlns:m="http://www.example.org/stock">
      <m:StockName>IBM</m:StockName>
    </m:GetStockPrice>
  </soap:Body>
</soap:Envelope>

REST (2000s-present)

Roy Fielding introduced Representational State Transfer (REST) in 2000 during his doctoral dissertation. REST is an architectural style for developing network applications using stateless communication and a uniform interface.

Key Principles of REST

• Stateless: Each service request to the server must contain all information that fully describes the one execution requested on the server.
• Client-Server Architecture: Separation of Concerns, with clients encapsulating the UI and the servers in charge of data storage.
• Cacheability: Responses should identify whether they are cacheable or otherwise for improved network efficiency.
• Uniform Interface: This is the standardized method and resource representation, such as HTTP methods like GET, POST, PUT, and DELETE.
• Layered System: A client cannot normally distinguish whether it is communicating directly with the end server or an intermediary on the path.

Advantages of REST

Below are some of the advantages of REST:

• Simplicity: Easy to understand and use.
• Scalability: Supports stateless operations; hence, it makes scaling easier.
• Flexibility: It can be used for various web or mobile applications.

Challenges of REST

We cannot talk about the advantages of REST without talking about the disadvantages:

• It does not return all the data the client needs or returns too much of the data that the client requires. It is stateless and requires authentication each time a request is made, which can affect the app's performance.
• It is not designed to update data in real time.

REST in Practice

RESTful APIs are the new web service standard that uses the JSON data exchange format. They are easy to consume and scale much better than modern web architectures. Every REST API has the following components: 1. Client: The client initiates the request using any of the following HTTP methods, namely GET, POST, PUT, or DELETE. 2. Request with HTTP Methods: The client sends a request to the server using the server resource address. 3. REST API Endpoint: This is the endpoint on the server where the HTTP requests are sent for processing. 4. Server: This processes the incoming request, executes the business logic, and communicates with the database if necessary. 5. Database: The server reads from or writes to the database depending on the client's requests.

REST Alternatives

While REST has been one of the oldest and most used styles for designing APIs and web services, other ways have been developed to overcome some of REST's drawbacks and fulfill the requirements of software developers. APIs act in relationship with these new standards in quite dissimilar structuring and interaction techniques; thus, one could state that each has advantages and disadvantages. Let's look at the popular REST alternatives:

GraphQL

GraphQL is a declarative query language created by Facebook in 2012 to become the new standard for API design and mitigate some of REST's limitations. It allows the client to define the data they expect, and the server responds with that exact data. It is mostly used as a REST alternative since it solves some issues with REST APIs, such as fetching unnecessary data or not fetching all the required data. It gives the client total control over the data returned on every request.

The unique features of GraphQL are:

• It provides a more flexible way to write queries by allowing clients to define the data they need from the server.
• Unlike REST, which has multiple endpoints, GraphQL uses a single endpoint to fetch all the data required by the client.
• GraphQL APIs are strongly typed, which can improve reliability and enable better tooling.

Let's compare GraphQL with REST data fetching:

From the diagram, you can see that REST data fetching involves making multiple API requests to the server to get the data needed by the client, while GraphQL makes a direct API call to the server to fetch the data it needs.

gRPC

gRPC is an open-source remote procedure call created by Google for high-performance applications. It uses Google's Protocol Buffers as the interface definition form. It is built to support many programming languages for creating distributed systems used in different operating systems and application environments.

In a gRPC communication, we have the following components:

• Client: Begins a gRPC call.
• gRPC Stub: The actor who resides on the application's client-side and translates the method calls the client side makes into gRPC requests.
• HTTP/2: Used as the communication protocol that HTTP functions in transferring the gRPC requests and responses.
• Protobuf: The format used to serialize and deserialize messages concerning the case of AWS and JMS.
• gRPC Server: Processes the gRPC requests and returns the answers.
• Service Implementation is the part of the service where the requested functions run and where most of the processing occurs on the server side.

Below is an example of what a gRPC API would look like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
syntax = "proto3";

package myapp;

service User {
  rpc GetUser (UserRequest) returns (UserReply) {}
}

// The request message containing the user's name.
message UserRequest {
  string name = 1;
}

// The response message containing the user's information
message UserReply {
  string message = 1;
}

Beyond Just Data Fetching

Today's APIs are far from simple data requests. They now support interaction, real-time updates, and intricate system structures. Let's discuss some of the more complex ideas defining the future of APIs.

Event-Driven APIs

As the name suggests, Event-driven architecture (EDA) is an architecture where the crux is an event that leads to interaction or a result. This event can be of several types, and how these events are conveyed to the end user is typically the most important aspect of the EDA implementation.

The changes that occur in a state that leads to an event can be transmitted through many different systems, but there are two common paradigms for such systems: the publish/subscribe and the publish/subscribe. In the pub/sub model, a user signs up for an update service, and as soon as an update is made, the subscriber is informed via an endpoint service. In the produce/consume model, the producer accumulates these events and can either release them one by one or as a stream; on the other end, the consumer engages with this model as a consumption model. The following diagram briefly shows how event-driven API architeture works in a web application.

Hypermedia and HATEOAS

HATEOAS is an acronym that stands for Hypermedia as the Engine of Application State, a principle that requires APIs to inform clients about the available actions, resources, and transitions within the API. This means that when using a RESTful API that implements HATEOAS, you do not have to rely on documentation outside the actual API to know how to use it. However, to avoid this, the API provides links and instructions in its responses to its functions and capabilities.

Unlike other APIs, which use static documentation to inform the client how to use the service, hypermedia-driven APIs offer this information at runtime.

API Gateways and Microservices

An API Gateway is an intermediary interface between clients and a set of backend services in the microservices architecture that deals with routing, service combination, and protocol transformation. It is similar to a receptionist, who directs clients to the appropriate services without their need to understand the organization's workings.

This relieves developers from having to work on creating single services without worrying about the number of backend APIs that will be required. They reduce the complexity of client interactions and enhance the system's capacity and protection.

The diagram about explains how it works in a web application. Let's look at the components of API Gateways and Microservices architecture. 1. Client: Starts requests, further launching them to the API Gateway. 2. API Gateway: This would act as the single entry point, handling and forwarding the request to the right microservice. 3. Microservices: Microservices have the concept that each can be solely held accountable for a particular functionality of an application. API Gateway forwards the requests to the correct microservices. 4. Databases: Every microservice has its database or a database common to all the microservices.

Future Trends in APIs

As technology evolves, so do APIs to meet new challenges and opportunities. APIs have become core to modern software development, and their importance has continued to increase. These changes will shape how we build and connect digital systems in the coming years. Now, let's take a look at some of the key trends that will help define the future of APIs:

• API Security: As the API becomes part and parcel of each use case, its security becomes crucial. This includes developing a robust security and data protection strategy, such as OAuth, OpenID Connect, and API gateways.
• Serverless Architectures: It is a computing concept that helps users define and execute applications that do not entail handling the base platforms. APIs are used at an incredibly high level here due to the microservice approach and the FaaS concept.
• API Integration with Machine Learning and AI: This is very useful for integrating machine learning and AI services, where an application can use the advanced algorithms and models used for its development.
• API standardization and governance: As APIs spread even more in coming years, concerns about their standardization and management will be quite critical, particularly with regard to the quality, dependability, and security within the numerous systems.

Conclusion

In this article, we have discussed the evolution of APIs from early computing interfaces to the contemporary RESTful APIs and other styles, which constitute the supersonic velocity of software advancement. Awareness of this field's past and present state enables developers to select the right tools and practices to create well-constructed sterile systems.