What is REST API?
Tags: python, rest, endpoint, api
Published: 2023-11-08 21:22:04

REST is acronym for Representational State Transfer. REST API is an architectural style for designing networked applications, particularly web services. It defines a set of constraints and principles that enable communication between different systems over the internet. If we design an API using REST architecture, that API is called REST API.

Before getting into REST APIs, let us understand some terms:

## Web APIs
Web APIs, also known as HTTP APIs or RESTful APIs, are APIs that are accessed over the web using the HTTP protocol. They allow applications to request and exchange data using standard HTTP methods such as GET, POST, PUT, and DELETE. Web APIs are widely used for building web applications, mobile apps, and integrating different systems.

## Endpoint
It is a specific URL or URI (Uniform Resource Identifier) that corresponds to a specific resource or functionality of the API. Each endpoint typically represents a specific operation or data entity that the API provides access to. 
The API might have an endpoint like https://api.weather.com/forecast. This endpoint is responsible for retrieving weather forecasts.

## HTTP Methods
HTTP methods, also known as HTTP verbs, are used to indicate the type of operation being performed on a resource through an API. 

The most common HTTP methods used in web APIs are:

### GET Method
The primary purpose of an HTTP GET request is to retrieve data from a server. It is used when a client wants to access or fetch a specific resource or information from a server. GET requests commonly include parameters appended to the URL as a query string. Parameters are key-value pairs separated by ampersands (&). 
For example: https://example.com/api/data?key1=value1&key2=value2. The server can use these parameters to provide specific data or filter the response.

Unlike other HTTP methods like POST or PUT, a GET request does not include a request body. The parameters or data associated with the request are usually sent as part of the URL itself.

### POST Method
The primary purpose of an HTTP POST request is to submit or send data to a server for processing or storage. It is used when a client wants to create a new resource, update an existing resource, or perform other actions that involve sending data to the server.

Unlike an HTTP GET request, a POST request includes a request body that carries the data being sent to the server. The data can be in various formats such as JSON, XML, form data, or binary data, depending on the requirements of the server-side application. The data to be sent is encapsulated within the request body. It can contain any necessary parameters, fields, or content that the server expects for the requested action or operation.

POST requests are commonly used when submitting sensitive or confidential data, such as user credentials or payment information. It is important to ensure the use of secure connections (HTTPS) and proper authentication and authorization mechanisms to protect the transmitted data.

### PUT Method
The primary purpose of an HTTP PUT request is to update or replace an existing resource on the server. It is used when a client wants to modify the state or content of a resource with a new representation provided in the request.

Similar to an HTTP POST request, a PUT request includes a request body that carries the data being sent to the server. The data contains the new representation of the resource to be updated or replaced. When making a PUT request, the client typically sends the complete representation of the resource, including any unchanged fields. The server uses this complete representation to update or replace the existing resource.

### PATCH Method
The primary purpose of an HTTP PATCH request is to perform a partial update on an existing resource. It is used when a client wants to modify specific fields or properties of a resource without sending the complete representation of the resource.

Similar to an HTTP PUT request, a PATCH request includes a request body that carries the data being sent to the server. The data contains the changes or updates to be applied to the resource. Unlike a PUT request, which typically replaces the entire resource, a PATCH request only modifies the specific fields or properties specified in the request body. Other fields or properties not included in the request body remain unchanged. When making a PATCH request, the client does not need to provide the complete representation of the resource. It can send only the fields or properties that require updating, minimizing the amount of data sent over the network.

### DELETE Method
The primary purpose of an HTTP DELETE request is to request the removal or deletion of a specific resource on the server. It is used when a client wants to delete a resource permanently. An HTTP DELETE request typically does not include a request body. Since the request is focused on resource deletion, no additional data is needed in the request body. The DELETE request is sent to a specific URL that represents the resource to be deleted. The server identifies and deletes the corresponding resource based on the URL provided.

## HTTP Request
An HTTP request is a message sent by a client to a server using the Hypertext Transfer Protocol (HTTP). It is the fundamental means of communication between clients (such as web browsers or applications) and servers on the World Wide Web. 

An HTTP request consists of several components:

1. HTTP Methods
2.	Request URL: The Uniform Resource Locator (URL) or Uniform Resource Identifier (URI) specifies the location and identifier of the requested resource. It typically consists of a protocol (e.g., "http://" or "https://"), domain name or IP address, and optional path, query parameters, or fragment identifier.
3.	Request Headers: HTTP headers provide additional information about the request or the client to the server. They include details such as the client's User-Agent, Accept-Language, Content-Type, and more. Headers can be used for authentication, content negotiation, caching directives, and other purposes.
4.	Request Body (Optional): In certain HTTP methods like POST, PUT, or PATCH, a request body can be included to send data to the server. The request body contains the payload or content being sent, typically in a specified format such as JSON, XML, or form data.
5.	Cookies (Optional): HTTP requests can include cookies, which are small pieces of data stored by the client and sent to the server with each request. Cookies are often used for session management, user authentication, and tracking user preferences.

## HTTP Response
An HTTP response is a message sent by a server to a client in response to an HTTP request. It is the server's way of communicating the outcome of the request and providing the requested data or other relevant information.

An HTTP response consists of several components:

1.	Response Status Line: The response status line includes the HTTP version, a numeric status code, and a brief textual description of the status. The status code indicates the outcome of the request, such as success, redirection, client or server errors, or other conditions.
2.	Response Headers: HTTP response headers provide additional information about the response, server, and requested resource. They include details such as Content-Type, Content-Length, Cache-Control, Set-Cookie, and more. Headers can provide instructions for caching, content negotiation, security, and other purposes.
3.	Response Body: The response body contains the actual content or data requested by the client. The format and content of the response body depend on the server's implementation and the nature of the requested resource. It can be HTML, JSON, XML, binary data, or any other supported format.
4.	Cookies (Optional): HTTP responses can include cookies, which are small pieces of data sent by the server and stored by the client. Cookies can be used for session management, user authentication, and other purposes. The client typically includes these cookies in subsequent requests.
5.	Other Meta-information: Depending on the specific circumstances and server configuration, an HTTP response may include additional meta-information. This can include response time, server version details, security-related headers, and more.

## Request Parameters
API endpoints often accept parameters that provide additional information to customize the request or specify the desired data. Parameters can be sent as part of the URL (query parameters) or in the body of the request (request body parameters).

For example, The location=NewYork part in the URL is a query parameter that specifies the location for which the forecast is requested. API endpoints often accept various parameters to customize the request.

Overall REST architecture follows certain set of rules for endpoints, methods, headers and for data. Whenever API interaction, client sends a request and server send a response. Request may be any above specified HTTP method.  APIs can be configured to send response in any configured format, either Json or XML format. 

REST APIs are stateless, meaning that the server does not store any client session information. Each request from the client to the server contains all the necessary information for the server to understand and process the request. The server does not maintain any client context between requests. These APIs expose resources, which are the fundamental entities or data entities that clients can interact with. Resources are typically identified by unique URLs (Uniform Resource Locators) or URIs (Uniform Resource Identifiers). 

REST APIs follow the four basic CRUD operations: **Create**, **Read**, **Update**, and **Delete**. These operations map to the standard HTTP methods such as **POST**, **GET**, **PUT/PATCH**, and **DELETE**, respectively. Each method performs a specific action on a resource. They use a uniform and consistent interface for interacting with resources. They adhere to standard HTTP methods and utilize HTTP status codes to indicate the result of a request. They also leverage standard data formats, such as JSON (JavaScript Object Notation) or XML (eXtensible Markup Language), for representing and exchanging data. REST APIs separate the concerns between the client and the server. The server is responsible for handling requests and processing data, while the client is responsible for the user interface and user experience.

REST APIs provide a scalable and interoperable approach to building distributed systems. They are widely used in web development to expose and consume data and services across different platforms, devices, and technologies. APIs that adhere to the principles of REST are commonly referred to as RESTful APIs.