REST API in a nutshell.

Last time, I talked about API and the various types of API that exist. Today I am focusing on REST API in specific. Watch out for the article for the other types of API.

Think of REST API as a set of rules for how computers talk to each other over the internet. It is like a language that they use to understand each other. API is like a menu in a restaurant. It has a list of dishes one can order, along with a description of each dish. When one specifies what they like, the Kitchen(i.e. the System) prepares the dish and then serves it.

REST works in the same way. The dishes are "pieces" of data or services provided by a server and the "Kitchen" is the server that prepares and serves them. The menu(API) tells you what you can order(request) and the kitchen(server) does the cooking(processing) and gives you the dish(response). So a REST API is a way for different computer systems to communicate over the internet by following specific rules, just like a menu at a restaurant helps you order food. It is a way for one computer to request and receive data or services from another computer, making the internet and other apps work. It is made up of the following components:

Resources.

Resources represent entities or Objects, such as data, services, or even real-world entities such as Products, Customers, or orders. Each resource is identified by a Unique URL(Uniform Resource Locator), often referred to as URI(Uniform Resource Identifier). For example, a product resource might have a URI like api.example.com/products/123, where "123" is the unique identifier of a specific product.

HTTP method.

HTTP methods define the operations that can be applied to Resources. REST uses CRUD operations:

• GET: Used to receive data from the server. For example, fetching product details.

• POST: Creates a new resource on the server. For example, adding a product to the catalog.

• PUT Updates a resource at a specific URL. For example, updating the product details of a particular existing product.

• DELETE: Removes a resource from the server at a specific URL. For example, Deleting a product from the server.

Some describe this method as HTTP verbs. They are fundamental components of how REST works.

URIs(Uniform Resource Identifier).

These are used to uniquely identify resources. They are hierarchical and follow a consistent structure which can be as simple as api.example.com/resource-name/resource-id..., making it easy for developers and clients to understand organizations API.

Statelessness.

REST by design is stateless. This means that each request from the Client to the server should contain all the information necessary for the server to understand and process the request. This architectural constraint simplifies the Server implementations and promotes scalability.

Representations.

Resources have several representations which include but are not limited to XML, JSON, or HTML. Clients specify their preferred representations using the accept header in their requests. For example, a client may request product data using JSON format.

Status codes.

HTTP status codes are used to indicate the outcome of a request. Some common status codes include:

• 200(OK) for a successful response.

• 201(Created) for a successful resource creation.

• 404(Not Found) for when a requested resource cannot be found.

• 500(Internal error) for server-related errors.

Request and Response Headers.

HTTP headers contain metadata and control information for requests and responses. Common headers include Content-Type(specifying the media type of the representation) and Authorization( for Authentication).

RESTful APIs.

This is a type of specific API that follows the principles of REST. It follows a clear, predictable structure and URL patterns. For example, a RESTful e-commerce API might use URIs like /products to list all the products and /products/123 to access a specific product with ID 123.

Authentication and Security.

To protect resources, REST APIs often use methods like API keys, OAuth, or tokens for authentication and authorization. Authentication mechanisms ensure that only authorized users can access specific resources.

Pagination and Filtering.

When dealing with large data sets, APIs often implement pagination to limit the number of results returned in a single request. Filtering allows clients to specify criteria to narrow down results. For example, Filtering products by category or price range.

Versioning.

APIs should have versioning mechanisms to maintain backward compatibility when making changes. This ensures that existing clients continue to work without issues while newer versions are developed.

HATEOAS(Hypermedia as the Engine of Application State).

This is an optional principle in REST where the server provides links to the related resources in the response. Clients can use these links to navigate the API dynamically, reducing the need for prior knowledge of the API's structure.

Common Data Formats.

JSON(JavaScript Object Notation) and XML (extensible markup language) are common data formats used for representing data in REST APIs. JSON has gained popularity due to its simplicity and readability.

Testing.

Tools like Postman and cURL are commonly used for testing REST APIs by sending requests and examining responses.

Tools and Frameworks.

various tools and frameworks can help with building and consuming REST APIs. For example, Express.js, Django, and Flask for API development, and various client libraries for consuming APIs.

Phew, that was a lot. I appreciate your time and see you in the next.

Special credits to @ainasanghi on X(Formerly Twitter).