REST and REST APIs - Part 1

This blog will talk about REST and RESTful APIs and will lead its way to the Backend Dev Blog.

So what is REST?

REST is an acronym for REpresentational State Transfer. It is a software architectural style or design pattern. An architectural pattern is a general, reusable solution to a commonly occurring problem in software architecture within a given context. Architectural patterns are often documented as software design patterns. REST was originally designed as a Web Architecture and its principles were presented by Roy Fielding, a computer scientist in his Ph.D. dissertation in 2000. REST-compliant systems, often called RESTful systems, are characterized by how they are stateless and separate the concerns of the client and server.

Some other Architectural Styles.

There are many recognized architectural styles and design patterns, among them:

• Blackboard

• Client-server (2-tier, 3-tier, n-tier, cloud computing exhibit this style)

• Component-based

• Data-centric

• Event-driven (or implicit invocation)

• Layered (or multilayered architecture)

• Microservices architecture

• Monolithic application

• Peer-to-peer (P2P)

• Pipes and filters

• Plug-ins

• Reactive architecture

• Representational state transfer (REST)

• Rule-based

• Service-oriented

• Shared nothing architecture

• Space-based architecture

Disclaimer: I don't know about all of these. These are just to show what REST is and what are some of its alternatives.

Principles of REST

1. Uniform Interface: The following four constraints can achieve a uniform REST interface:

   • Identification of resources – The interface must uniquely identify each resource involved in the interaction between the client and the server.

   • Manipulation of resources through representations – The resources should have uniform representations in the server response.

   • Self-descriptive messages – Each resource representation should carry enough information to describe how to process the message. It must clearly convey information on the operations that can be done on a resource

   • Hypermedia as the engine of application state – The client should have only the initial URI of the application. The client application should dynamically drive all other resources and interactions with the use of hyperlinks.

2. Client and Server: The client is the entity that makes the demands and the server is the entity that handles the demands. The producer and consumer need to be separate for independent evolution. In the REST architectural style, the implementation of the client and the implementation of the server can be done independently without each knowing about the other. As long as each side knows what format of messages to send to the other, they can be kept modular and separate. Separating the user interface concerns from the data storage concerns, we improve the flexibility of the interface across platforms and improve scalability by simplifying the server components.

3. Statelessness: Systems that follow the REST paradigm are stateless, meaning that the server does not need to know anything about what state the client is in and vice versa. In this way, both the server and the client can understand any message received, even without seeing previous messages. This constraint of statelessness is enforced through the use of resources, rather than commands. Resources are the nouns of the Web - they describe any object, document, or thing that you may need to store or send to other services. This also means all the information needed to carry out a request is present in the request itself.

4. Cacheable: The cacheable constraint requires that a response should implicitly or explicitly label itself as cacheable or non-cacheable. If the response is cacheable, the client application gets the right to reuse the response data later for equivalent requests and a specified period.

5. Layered System: The layered system style allows an architecture to be composed of hierarchical layers by constraining component behavior. For example, in a layered system, each component cannot see beyond the immediate layer they are interacting with.

6. Code on Demand: This constraint is optional — an API can be RESTful even without providing code on demand. The client can request code from the server, and then the response from the server will contain some code, usually in the form of a script, when the response is in HTML format. The client then can execute that code.

What is a Resource?

In REST, a resource is an object or piece of data that can be identified and manipulated using a unique identifier or URL.

What are Resource Methods?

Resource methods are used to perform the desired transition between two states of any resource.

NOTE: A large number of people wrongly relate resource methods to HTTP methods (i.e., GET/PUT/POST/DELETE). Roy Fielding has never mentioned any recommendation around which method to be used in which condition. All he emphasizes is that it should be a uniform interface.

REST and HTTP are Not the Same

Many people prefer to compare HTTP with REST. REST and HTTP are not the same. HTTP is the underlying protocol used for communication between clients and servers on the World Wide Web. REST, on the other hand, is an architectural style that provides a set of guidelines and constraints for designing web services that are scalable, reliable, and easy to maintain. During his dissertation, Roy Fielding never mentioned any direct implementation. He never talked about HTTP or any such protocols we use today.

REST APIs

This section is a leader to the Backend Development blog and will contain everything you need to know to get started with APIs.

What is an API?

An API (Application Programming Interface) is a set of protocols, tools, and standards for building software applications. It defines how different software components should interact with each other, allowing developers to create software applications that can communicate and exchange data with other systems. APIs can be used to access data, services, or functionality provided by other software applications, and they are essential for building modern web and mobile applications. You can think of a web API as a gateway between clients and resources on the web.

For example: Let's consider a restaurant. The customers who come in, and place the orders are the consumers. They are in this case known as the client. The producers are the chef and the kitchen crew, known here as the server (backend). The waiter is the entity that connects these two entities and ensures the smooth running of the restaurant (The software/app). Thus the waiter here is the API.

What are RESTful APIs?

A RESTful API is a type of web API that follows the principles of the REST architectural style. It is designed to provide a standard way of accessing and manipulating resource states over the web using various methods.

Why RESTful APIs

The benefits of using RESTful APIs include:

1. Scalability: RESTful APIs are designed to be scalable and can handle large volumes of requests and responses.

2. Flexibility: RESTful APIs can support different types of clients (e.g., web browsers, mobile apps, IoT devices) and can be used with different programming languages and frameworks.

3. Modularity: RESTful APIs are typically organized around resources, making them modular and easier to maintain.

4. Caching: RESTful APIs support caching of responses, which can improve performance and reduce server load.

5. Security: RESTful APIs can be secured using standard security protocols such as HTTPS and OAuth, making them more secure and less vulnerable to attacks.

6. Ease of Use: RESTful APIs are easy to use and understand, which makes them more accessible to developers of all skill levels.

Overall, RESTful APIs provide a standardized and scalable way to build modern web and mobile applications that can communicate and exchange data with other systems.

The Way of REST

The basic function of a RESTful API is the same as browsing the internet. The client contacts the server by using the API when it requires a resource. API developers explain how the client should use the REST API in the server application API documentation. These are the general steps for any REST API call:

1. The client sends a request to the server. The client follows the API documentation to format the request in a way that the server understands.

2. The server authenticates the client and confirms that the client has the right to make that request.

3. The server receives the request and processes it internally.

4. The server returns a response to the client. The response contains information that tells the client whether the request was successful. The response also includes any information that the client requested.

Client Request

What does the RESTful API client request contain? The components are:

1. Unique resource identifier: The server identifies each resource with unique resource identifiers. For REST services, the server typically performs resource identification by using a Uniform Resource Locator (URL). The URL specifies the path to the resource. It's called an endpoint.

2. Methods: Developers often implement RESTful APIs by using the Hypertext Transfer Protocol (HTTP). An HTTP method tells the server what it needs to do to the resource. The following are four common HTTP methods:

   1. GET: Clients use GET to access resources that are located at the specified URL on the server. They can cache GET requests and send parameters in the RESTful API request to instruct the server to filter data before sending.

   2. POST: Clients use POST to send data to the server. They include the data representation with the request. Sending the same POST request multiple times has the side effect of creating the same resource multiple times.

   3. PUT: Clients use PUT to update existing resources on the server. Unlike POST, sending the same PUT request multiple times in a RESTful web service gives the same result.

   4. DELETE: Clients use the DELETE request to remove the resource. A DELETE request can change the server state. However, if the user does not have appropriate authentication, the request fails.

3. HTTP headers: Request headers are the metadata exchanged between the client and server. For instance, the request header indicates the format of the request and response, provides information about the request status, and so on. It also has fields for authentication.

4. Parameters: RESTful API requests can include parameters that give the server more details about what needs to be done. The following are some different types of parameters:

   • Path parameters that specify URL details.

   • Query parameters that request more information about the resource.

   • Cookie parameters that authenticate clients quickly.

Server Response

What does the RESTful server response request contain? The components are:

1. Status line: The status line contains a three-digit status code that communicates request success or failure. For instance, 2XX codes indicate success, but 4XX and 5XX codes indicate errors. 3XX codes indicate URL redirection.

   The following are some common status codes:

   • 200: Generic success response

   • 201: POST method success response

   • 400: Incorrect request that the server cannot process

   • 404: Resource not found

2. Message body: The response body contains the resource representation. The server selects an appropriate representation format based on what the request headers contain. Clients can request information in XML or JSON formats, which define how the data is written in plain text.

3. Headers: The response also contains headers or metadata about the response. They give more context about the response and include information such as the server, encoding, date, and content type.

Common Response Status Codes

---

We can get a clear view of REST APIs in the next blog REST and REST APIs - Part 2. This should have provided you with a clear view of what REST APIs and REST are. If you still have any questions/queries you can reach out to me on my LinkedIn / GitHub / Twitter.

Cheers!