API, REST, and RESTful — What do these terms mean?

#api #rest #architecture

What is an API?

An Application Programming Interface (API) is a set of protocols, routines, and tools that define the methods and data formats by which a software component (the server) offers functionality and data to another software component (the client). It acts as a stable, abstract contract that hides the underlying implementation details, enabling decoupled communication between distinct software systems.

Historically, the API was defined simply as:

"A set of services available to a programmer for performing certain tasks."

Must Have

Requirement	Description
Interface Contract	A clearly defined, stable, and documented contract that specifies the operations (methods/functions) available, the required input parameters, and the expected output format and data types.
Abstraction	The interface must hide the internal complexity and implementation details of the underlying system. The consumer should only interact with the defined contract.
Programmatic Access	The interface must be designed for use by other software programs, not directly by a human user, typically through function calls or network requests.
Data/Functionality Exposure	The API must expose a specific set of data or functionality that is useful to the consumer, acting as a gateway to the provider's resources.

What is REST?

No, it's not this type of rest.

But actually...

Representational State Transfer (REST), first introduced by Dr. Roy Thomas Fielding in his doctoral dissertation at the University of California, is an architectural style for designing distributed hypermedia systems, such as the World Wide Web. It is not a protocol or a standard, but a set of architectural constraints applied to components, connectors, and data elements to achieve desired properties like performance, scalability, simplicity, and evolvability.

The six mandatory constraints are:

Client-Server: The principle of separation of concerns. The client handles the user interface and user state, while the server manages data storage and processing. This separation allows components to evolve independently.
Stateless: Communication must be stateless. Each request from the client to the server must contain all the information necessary to understand and complete the request. The server cannot rely on any stored session context. Session state is kept entirely on the client.
Cacheable: Data within a response must be explicitly or implicitly labeled as cacheable or non-cacheable, allowing clients and intermediaries to reuse response data.
Uniform Interface: This is the central feature that distinguishes REST from other network-based styles. It simplifies the overall system architecture and improves visibility. It is composed of four sub-constraints:

• Identification of Resources: Individual resources are identified in requests.

Example: To access a specific user, you'd use a URI like /users/123. The URI identifies the thing you want to interact with.

• Manipulation of Resources through Representations: Clients manipulate the state of a resource by transferring representations (e.g., JSON or XML documents) of the resource.

• Self-Descriptive Messages: Each message includes enough information to describe how to process the message. This often involves using standard media types.

• Hypermedia as the Engine of Application State (HATEOAS): The client's application state is driven by hypermedia links contained within the representations. The client navigates the application by following links provided in the server's responses, rather than having a pre-configured understanding of the URI structure; e.g.:
Request
```
 GET /orders/123 HTTP/1.1
 Host: api.example.com
 Authorization: Bearer <CLIENT_LOGIN_TOKEN_HERE>
 Accept: application/json
```
Response
```
 HTTP/1.1 200 OK
 Content-Type: application/json
 Content-Length: 205
 Date: Tue, 11 Nov 2025 22:45:50 GMT

 {
   "orderId": 123,
   "status": "PROCESSING",
   "total": 59.99,
   "currency": "USD",

   "_links": {
     "self": { "href": "/orders/123" },
     "cancel": {
       "href": "/orders/123/cancel",
       "method": "POST"
   },
   "items": { "href": "/orders/123/items", "method": "GET" }
  }
 }
```
Layered System: The architecture must be composed of hierarchical layers. A client cannot "see" beyond the immediate layer it is interacting with. This allows for the introduction of intermediaries (like load-balancers, proxies, and firewalls) to enhance security, scalability, and performance without affecting the client or server.
Code-On-Demand (Optional): This is the only optional constraint. It allows the client's functionality to be extended by downloading and executing code (e.g., applets or scripts) from the server.

The most common failure point for "RESTful" APIs is the violation of the Stateless (obs: every request must be complete and self-contained — no context or state stored on the server) and HATEOAS constraints. An API that uses sessions or requires a client to construct URIs based on documentation, rather than following links in the response, is not truly RESTful according to Fielding's original definition.

Read the original paper about REST here.

Thanks for your time!😎

Any thoughts, please leave your comments down below!✌️