API REST, after this you will be an expert
Communications between systems through REST APIs have become very popular in recent years, leaving aside the old SOAP protocol. In this article, we will cover some concepts that you may have heard before such as REST, RESTful API, HTTP Verbs, among others. On the other hand, we recommend you to review our article Basic HTTP - What you need to know, which will improve somewhat the understanding of what we will see next without being a requirement.
What is REST?
REST (Representational state transfer) is a software architecture style that defines a set of rules for communication between computer systems on the web. This set of rules makes the communication easier since the implementation of the client and server can be done separately, improving the interface flexibility across different platforms. The systems that are compatible with REST are called RESTful systems, and the APIs exposed by these systems are called RESTful APIs. One of the most important aspects of this architectural style is that by using a REST interface, different clients using the same endpoints perform the same actions and get the same responses.
Requests to a REST API
REST requires that a client performs a request which consists of the following characteristics:
- An HTTP verb, which defines the type of operation to be performed
- Some headers, which define certain information about the request
- A path or resource (usually a URI)
- An optional message body that contains data
HTTP Verbs
There are 4 basic types of HTTP verbs that define the type of operation to be performed:
- GET: To retrieve a resource or a set of specific resources
- POST: To create a new resource
- PUT: To update a specific resource
- DELETE: To delete a specific resource
Headers
Headers send certain information about the request, such as the type of content (JSON, XML, ...), character encoding, language, cookies, authentication information, among others. A very common header that you may encounter would be similar to the following.
Content-Type=application/jsonIn REST communication, the type of content is essential. A request could specify what type of message is expected through the accept header. In turn, a response generated for that request would deliver a message type defined by the Content-Typeheader.
Observe the following request made to a service that provides information about article number 23 in a database.
GET /articles/23 HTTP/1.1
Accept: text/html, application/xhtml
As indicated, the accept header allows the response to be html or xhtml. The headers sent as the service response are as follows.
HTTP/1.1 200 (OK)
Content-Type: text/html
As you can see, the content type delivered by the server is html, which is in the list of accepted content types by the client.
Paths
Requests must contain a path to a resource on which an operation will be performed. Paths must be descriptive and indicate in a friendly way what operation is being performed on some resource. For example, look at the following path.
someserver.com/customer/10/order/1This path indicates first the server on which the request is made. Second, it indicates that the customer with ID 10 and order number 1 are being consulted.
Message Body
The message body is all additional information that can be sent in a request, and all the information that is returned to us as a response from a REST service. The response to the request of the path indicated above could be the following.
{
customer: 10,
order: 1,
description: 'Purcharse order #1',
amount: '231.00',
currency: 'USD'
}
Response codes
Each request comes with an HTTP response code that indicates the status of that request. The most representative codes are the following:
| Code | Description |
| 200 (OK) | Successful request |
| 400 (BAD REQUEST) | The client's request is incorrect |
| 403 (FORBIDDEN) | The client does not have permission to perform the request |
| 404 (NOT FOUND) | The resource could not be found |
| 500 (INTERNAL SERVER ERROR) | There was an error on the server processing the request |
There is a range of intermediate codes which you can consult in more detail. However, it is not necessary to memorize each of them.
As an exercise, you could use Postman to test some public APIs and practice what you have learned. We hope that now you have a clearer understanding of the term REST, REST API, RESTful system, and all its derivatives. You can also visit our article Build a REST API with Laravel to apply what you have learned. See you soon!