REST API
A server is a computer with special software. A back-end is a program located on a server that can process incoming HTTP requests and has a set of ready-made actions for specific requests.
API(Application Programming Interface) is a set of well-defined communication rules between various software components. The interface describes what you can ask the program to do and what you will get as a result.
REST (representational state transfer) is a back-end architecture style based on a number of principles that describe how network resources are defined and addressed.
REST API is a back-end built on the REST principle. It serves as a layer between the web application and database. It has a standard interface for accessing resources. It works like a website: you send an HTTP request from the client to the server, and in response, instead of an HTML page, you receive data in JSON format.
Request format
A REST service requires the client to make a request to add, retrieve or modify data. Such request can consist of the following parts.
| Entry | Description |
|---|---|
| HTTP Method | Determines what operation to perform. |
| HTTP Headers | Enable the client to transfer additional request-related information. |
| Path | The path to the resource. All available paths are described in the back-end documentation. |
| Body | A request block containing data. |
HTTP methods
There are several basic HTTP methods for working with a REST service.
| Method | Description |
|---|---|
| POST | Creating a new resource |
| GET | Getting a set of resources or a single resource |
| PUT | Updating an existing or creating a new resource |
| PATCH | Updating an existing resource |
| DELETE | Deleting a resource |
HTTP headers
Headers contain additional information related to the content of requests. For example, the type of content that the client can process in the server’s response (the Accept header), or which describes the type of resource that the client sends to the server or the server sends to the client (the Content-Type header).
Accept: text/html
Content-Type: application/json
MIME types are content types. They are used to indicate the content of requests and responses; they consist of a type and a subtype separated by a forward slash /. For example, a text file containing HTML will be described as text/html type. If a file contains CSS, it will be described as text/css. JSON data will be described as application/json. If the client expects text/css, but receives application/json, it will not be able to recognize and process the response content.
Paths
Requests must contain the path to the handled resource. The available paths (endpoints, resources) are described in the back-end documentation.
GET https://bookstore.com/api/orders
Accept: application/json
Such path clearly specifies a resource, even if you have never seen it before, because it is hierarchical and descriptive. Make a request to get a collection of orders.
To get one element of the collection, its identifier is added to the resource. Consider a request to read one order with the identifier 289.
GET https://bookstore.com/api/orders/289
Accept: application/json
The last part of the path is called a dynamic parameter, which is described in the documentation as /resource/:parameter. The resource is permanent, it is the path to the entire collection, whereas the parameter value changes for each of its elements.
Response codes
The server sends a response to the client's request, which contains a status code to inform the client about the operation result. These codes are divided into groups.
| Group | Description |
|---|---|
| 1XX | For information purposes |
| 2XX | Success codes |
| 3XX | Describe everything related to redirection |
| 4XX | Indicate customer errors |
| 5XX | Indicate server errors |
You do not have to remember all codes from each group – it is enough to know the most common ones. The rest can always be found in the List of HTTP Status Codes.
| Code | Description |
|---|---|
| 200 (OK) | Standard response for successful HTTP requests. |
| 201 (Created) | Standard response for the HTTP request that resulted in the successful creation of a new resource. |
| 400 (Bad Request) | The request cannot be processed due to invalid request syntax or other client error. |
| 401 (Unauthorized) | Authorization is required to access the resource. |
| 403 (Forbidden) | The client does not have permission to access this resource. |
| 404 (Not Found) | The resource is not found. It may have been deleted or may not exist yet. |
| 500 (Internal Server Error) | General response to unexpected server crash unless more specific information is available. |
Request-Response
Suppose you have an application to view, create, edit and delete customers and orders from a small bookstore, with a back-end hosted at bookstore.com/api. Using your knowledge, describe the request-response process for the back-end with pseudocode.
If you want to get data about all customers, your GET request will look like this.
GET bookstore.com/api/customers
Accept: application/json
To which the server will send you the following response.
Status: 200 OK
Content-Type: application/json
Body: JSON data for all customers
To receive the data for one customer, enter his/her identifier, specifying your GET request.
GET bookstore.com/api/customers/289
Accept: application/json
To which the server will send you the following response.
Status: 200 OK
Content-Type: application/json
Body: JSON customer data
In order to add a new customer, make a POST request.
POST bookstore.com/api/customers
Content-Type: application/json
Body: { "username": "Mango", "email": "mango@gmail.com" }
The server adds a unique identifier and returns the entire object as a result.
Status: 201 Created
Content-type: application/json
Body: { "id": 18674, "username": "Mango", "email": "mango@gmail.com" }