REST/CRUD

What is an API?

In the context of a web platform, an API (Application Programming Interface) is an interface between the different parts of the platform. It is the way the different parts of the system communicate with each other. For example the backend could expose an API that the frontend consumes in order to retrieve information to display in a web page.

HTTP Verbs

The HTTP protocol defines methods (usually called verbs) to indicate the desired action to be performed on a specific resource. The most commonly used HTTP verbs are:

• GET: requests a representation of the specified resource. Requests using GET should only retrieve data and should have no other effect.
• POST: requests that a web server accepts the data enclosed in the body of the request message, most likely for storing it. It is often used when uploading a file or when submitting a completed web form.
• PUT: replaces the resource at the current URL with the resource contained within the request. PUT is used to both create and update the state of a resource on the server
• PATCH: applies partial modifications to a resource. It is mostly used to update a resource.
• DELETE: deletes the specified resource
• OPTIONS: returns the HTTP methods that the server supports for the specified URL. This can be used to check the functionality of a web server
• HEAD: asks for a response identical to that of a GET request, but without the response body. This is useful for retrieving meta-information written in response headers, without having to transport the entire content.

REST

REST (REpresentational State Transfer) is about constraining the way we interact between client and server, to take advantage of what the protocol (in this case, HTTP) offers. These constraints give us freedom to focus on our API design:

1. Uniform interface: requests from different clients look the same, whether the client is a browser, mobile device, or anything else.
2. Client-server separation: the client and the server act independently and the interaction between them is only in the form of requests and responses.
3. Stateless: the server does not remember anything about the user who uses the API, so all necessary information to process the request must be provided by the client on each request. Note: this isn't about storing server-side state.
4. Layered system: the client is agnostic as to how many layers, if any, there are between the client and the actual server responding to the request. This is a key principle of HTTP, allowing for caching servers, reverse proxies, and access security layering – all transparent to the client sending the request.
5. Cacheable: the server response must contain information about whether or not the data is cacheable, allowing the client and/or intermediaries (see layered constraint, above) to cache data outside of the API server.
6. Code-on-demand (optional): the client can request code from the server, usually in the form of a script, for client-side execution.

CRUD

CRUD stands for Create, Read, Update and Delete. In the context of a RESTful API, we want them to have a standarized use of HTTP verbs and each action on our API will map to a specific CRUD action in a database.

Example RESTful API endpoints

If our system handles photos and we want to have an API to expose them, this could be a list of endpoints we will have in our RESTful API: