What is REST

REST, which stands for REpresentational State Transfer, is an established architecture for creating Web APIs. REST services can use the HTTP protocol (as well as other protocols like SMTP, SNMP) for data exchange. The REST architecture guidelines indicate using a specific HTTP method for a particular type of call.
The set of HTTP methods (also called verbs), such as GET, POST, PUT, and DELETE, simplifies the correspondence between CRUD actions (Create, Read, Update, Delete) and the HTTP calls we will make:

HTTP Method	CRUD Operation	Description
POST	Create	Creates a new resource
GET	Read	Gets an existing resource
PUT	Update	Updates (replaces) a resource or modifies its state
DELETE	Delete	Deletes a resource
PATCH	Update (partial)	Partially updates the resource
OPTIONS		Returns information about a specific resource (allowed methods for a resource)

REST service calls are made by specifying the HTTP method, URL, resource, and any information related to the type of request. For example, to invoke the data reading service, we could make a GET request to the address:


In this example, the URL is https://www.servername.cloud, while api is the directory that exposes REST services within the server. The resource we want to access for reading is articles (these could be articles available in a warehouse), and finally 3 represents the key, or identifier, of the article we want to read.
If the call is successful, the service will respond by sending the resource data to the client. The response format can be JSON, XML, HTML, or text.

Response Codes

After invoking a REST service, to understand if our request was successful or not, we must verify the status sent by the server. It's a 3-digit numeric code, where the first digit defines its type:

• 1xx: information codes
  Example:
  • the code 100 Continue notifies the client that the initial part of the request has been received and hasn't been rejected by the server; the client should send the remaining part of the request or ignore the code if it has already sent the rest.
• 2xx: success codes
  Example:
  • the code 200 OK indicates that the request was successful;
  • the code 201 Created indicates that the request was successful and the resource was created (this code is returned, for example, with a POST request);
  • the code 202 Accepted indicates that the request has been received but not yet completed. It is typically used in batch processing requests.
• 3xx: redirection codes
  Example:
  • the code 301 Moved Permanently indicates that the requested resource's URL has been permanently changed. The new URL is indicated in the Location field of the header.
• 4xx: client error codes
  Example:
  • the code 400 Bad Request indicates that the request cannot be processed by the server due to incorrect syntax. The client should not repeat the request without modifying it first;
  • the code 401 Unauthorized indicates that the request requires user authentication. The client can repeat the same request after properly setting the Authorization field;
  • the code 404 Not Found indicates that the server cannot find the requested resource, for example, via GET;
  • the code 409 Conflict indicates that the server cannot complete the request due to a conflict with the current state of the resource.
• 5xx: server error codes
  Example:
  • the code 500 Internal Server Error indicates that the server encountered an unexpected condition that prevented it from fulfilling the request;
  • the code 501 Not Implemented indicates that the HTTP method is not supported by the server and therefore cannot be handled;
  • the code 503 Service Unavailable indicates that the server is not ready to handle the request.

Examples with Postman

Let's look at some examples of REST services that can be invoked without any authentication method.
We will use the open-source service https://randomuser.me, through which you can generate random user data.
To test this service, we will use Postman, a tool that allows, among other things, to invoke REST APIs. Postman can be downloaded from this address.
After installing and launching it, simply insert a new request with the GET method and enter the URL https://randomuser.me/api/:



To execute the request to the REST service, simply click on Send. In the lower panel, you can verify the success of the request by checking that the status is 200 OK. In this case, the Body panel displays the request output, which is the random data of a user:It's possible to generate data for multiple users with a single service call.
To do this, simply modify the URL to: https://randomuser.me/api/?results=3 to generate data for three users.
You can also decide which information to generate for each user. For example, to have only the data related to name, email address, and phone number, you can use this API: https://randomuser.me/api/?inc=name,email,phone.
The result is:Of course, you can combine multiple parameters in the service call by separating them with the & character:
https://randomuser.me/api/?results=3&inc=name,email,phone
The service response will be:
In the next article, we will see how to create a set of APIs to handle CRUD operations on a resource.