API Bakery

How REST bulds on top of HTTP

REST (Representational State Transfer) is a set of architectural principles that dictate how web APIs should be designed and implemented. REST APIs are built using HTTP, the most widely used protocol for communication on the web.

HTTP (Hypertext Transfer Protocol) is a simple and flexible client-server protocol that allows users to access and interact with web resources. It is based on a request-response model. This means that when a client (such as a web browser) wants to access a resource on a server (such as a web page), it sends a request to the server. The server then processes the request and sends back a response, which may include the requested data or an error message.

One of the key features of HTTP is that it is a stateless protocol, meaning that it does not maintain any information about the state of the client. This allows the server to handle multiple requests simultaneously, without having to keep track of the state of each individual client.

Another important feature providing flexibility is the use of headers, which provide additional information about the request or response. For example, the Content-Type header specifies the media type of the data being sent or received. Other common headers include Accept (specifying the acceptable media types for the response), Authorization (specifying authentication information), and Cache-Control (specifying caching directives).

HTTP defines a set of request methods that specify the action to be performed on the requested resource. The most commonly used request methods are "GET" (to retrieve a resource), "POST" (to create a new resource), "PUT" (to update an existing resource), and "DELETE" (to delete a resource).

The URL (Uniform Resource Locator) path is another key feature of HTTP. It specifies the location of the resource being requested, and can include query parameters to further specify the request. For example, the URL http://example.com/users?page=2 specifies a request for the "users" resource on the "example.com" domain, with the query parameter "page" set to "2".

In addition to headers and request methods, HTTP also defines a set of response status codes that indicate the result of the request. The most common status codes are "200 OK" (indicating a successful response), "404 Not Found" (indicating that the requested resource does not exist), and "500 Internal Server Error" (indicating that an error occurred on the server).

Media types, also known as MIME (Multipurpose Internet Mail Extensions) types, are another important concept in HTTP. They specify the format of the data being sent or received, such as application/json for JSON data or text/html for HTML content.

REST APIs leverage the features of HTTP to provide a simple and flexible way to access and interact with web resources. They use HTTP headers, request methods, and URL paths to specify the details of the request, and use HTTP response status codes and media types to specify the details of the response.

For example, a REST API might use the "GET" request method to retrieve a list of users, with the URL http://example.com/users and the application/json media type for the response. The server would then return a 200 OK response with a JSON-formatted list of users.

One of the key benefits of using REST APIs is that they are built on top of HTTP, which is a widely supported and well-understood protocol. This makes it easy for developers to integrate REST APIs into their applications, and for users to access and interact with web resources using familiar tools and technologies.

Request methods

The most commonly used HTTP methods in REST APIs are GET, POST, PUT, PATCH, and DELETE. An important aspect of each method is whether it's "safe" and "idempotent".

The GET method is used to retrieve data from the server. It is considered a "safe" method, which means that it does not have any side effects and can be called without any risk of changing the state of the server. GET requests are also idempotent, which means that multiple identical requests will have the same effect as a single request, so the request can be safely repeated.

An example of a GET request in a fictional REST API is:

GET /users/1 HTTP/1.1
Host: example.com

The POST method is used to submit data to the server, typically for the purpose of creating a new resource. It is not considered a safe method, because it can have side effects (such as creating a new resource on the server). POST requests are not idempotent, because multiple requests will have different effects (e.g., creating multiple new resources).

An example of a POST request in the same API might be:

POST /users HTTP/1.1
Host: example.com

{
  "name": "John Doe",
  "email": "johndoe@example.com"
}

This request would create a new user on the server with the specified name and email address.

The PUT method is used to update a resource on the server. It is not considered a safe method, because it can have side effects (such as modifying the state of the server). However, PUT requests are idempotent, because multiple identical requests will have the same effect as a single request.

An example of a PUT request in a REST API:

PUT /users/1 HTTP/1.1
Host: example.com

{
  "name": "Jane Doe",
  "email": "janedoe@example.com"
}

This request would update the user with an ID of 1 on the server, setting their name and email address to the specified values.

The PATCH method is used to partially update a resource on the server. It is not considered a safe method, because it can have side effects. However, like PUT requests, PATCH requests are idempotent, because multiple identical requests will have the same effect as a single request. Unlike with PUT, the request would include only the data that needs to be updated, such as the user's updated name. The server would then update the user with this data and return a response to the client.

Here's an example of a PATCH request:

PATCH /users/1 HTTP/1.1
Host: example.com

{
  "name": "Jane Doe"
}

The DELETE method is used to delete a resource from the server. It is not considered a safe method, because it can have side effects. However, like PUT and PATCH requests, DELETE requests are idempotent, because multiple identical requests will have the same effect as a single request.

An example of a DELETE request:

DELETE /users/1 HTTP/1.1
Host: example:com

Note that safeness and idempotency of methods are standard best practices, not something enforced by the protocol itself. It is up to the service programmers to ensure the API endpoints they implement follow these pratices. A well designed and implement API will follow the guidelines, but when using a new API, users are advised to first check these assumptions.

Status codes

HTTP status codes are used in REST APIs to indicate the result of a request. Status codes beginning with 2 (200 - 299) indicate success. Those beginning with 3 (301, 302, 308) indicate redirection. Status codes starting with 4 (400 - 499) signal client error, while those starting with 5 (500 - 599) mean there's a problem with the service.

There are many badly designed APIs out there that return 200 OK for everything and signal the error in the response body. While the response body can (and should) be used to display additional details in case there's an error, the status code itself should properly reflect the status of the operation.

Success

The 200 OK status code indicates that a request was successful. This is the most commonly used status code, and it is returned whenever a request is able to be successfully completed.

The 201 Created status code indicates that a new resource was created. This status code is typically returned in response to a POST request, which is used to create a new resource on the server.

The 204 No Content status code indicates that a request was successful, but the server has no data to return. This status code is typically used in response to a DELETE request, which is used to delete a resource from the server.

Client error

The 404 Not Found status code indicates that the requested resource was not found on the server. This can happen if the client is trying to access a resource that does not exist, or if the client is using an incorrect URL.

The 400 Bad Request status code indicates that the request was invalid. This can happen if the client is sending a request with incorrect or missing data. The response body should provide details on what was incorrect or missing (validation errors).

The 401 Unauthorized status code indicates that the client is not authorized to access the requested resource. This can happen if the client is not logged in or does not have the necessary permissions (though in the latter case, status code 403 is preferrable).

The 403 Forbidden status code indicates that the client is not allowed to access the requested resource. This can happen if the client is logged in, but does not have the necessary permissions. Distringuishing between this and 401 helps the client understand whether the problem is in authentication (client must log in), or authorization (client's identity is known but it's still forbidden from executing this operation).

Server error

The 500 Internal Server Error status code indicates that the server encountered an error while processing the request. This is a general error code that is used when the server is unable to complete a request for some reason. In general, 5xx codes mean there's a server problem.