REST API Tutorial

An API (Application Programming Interface) allows different software applications to communicate with each other. It defines the methods and data formats that applications can use to request and exchange data.

REST (REpresentational State Transfer) is an architectural style for designing networked applications. It relies on a stateless, client-server, cacheable communications protocol – the HTTP. RESTful applications use HTTP requests to perform CRUD (Create, Read, Update, Delete) operations on resources and return data in various formats, often JSON or XML.

An API that follows the REST standard is called a RESTful API or REST API. A REST implementation should be stateless. It means the two parties don’t need to store any information about each other, and every request and response (cycle) is independent from all others. It uses standard HTTP methods and can return data in various formats, often JSON or XML.

HTTP Methods in REST

HTTP methods in RESTful API development to specify the type of action being performed on a resource. There are five essential HTTP methods:

• POST: Create a new resource. (CREATE)
• GET: Retrieve information about a resource. GET requests do not change the resource’s state, so it is said to be a safe method (READ)
• PUT: Update an existing resource by replacing its content entirely. (UPDATE)
• DELETE: Delete a resource. (DELETE)
• PATCH: Apply partial modifications to a resource.

The first four methods’ functions are called CRUD (Create, Read, Update, Delete).

Remember: PUT for update, POST for create.

Although POST and PUT can be used to create new resources but there are some differences between them. You can find out the difference in the table below:

Criteria	POST	PUT
Usage	Create a new record	Update a record
Idempotent*	non-idempotent	idempotent
Request Body	only need to send the part to be updated in the request	needs to send the entire resource as payload
Status Code	+ 201 is sent in response if new record is created successfully + 409 if duplicates are not allowed	+ 200 when record gets updated + 201 if this record is new

*Note: PUT is an idempotent method, while POST isn’t. For instance, calling the PUT method multiple times will either create or update the same resource. In contrast, multiple POST requests will lead to the creation of the same resource multiple times.

In the body of these requests, there could be an optional HTTP request body that contains a custom payload of data, usually encoded in JSON. The server receives a request, processes it

When a response is replied from the server, a status code is also attached to tell the result.

2xx: The request was successful
4xx: Something wrong with the request
5xx: Something wrong at the server

Examples of HTTP methods

We wrote a tutorial which uses Postman to send REST API to a CSR1000v router here. You will find many examples of how to use HTTP methods. Below is an example of using GET method:

POST method example. The body of POST method contains the configuration of the Loopback101 interface:

DELETE method:

Note: {{host}} and {{port}} are two variables which we defined before using.

Principles of REST

1. Stateless: Each request from a client to the server must contain all the information needed to understand and process the request. The server cannot store any client context between requests.

2. Client-Server Architecture: The client is the front-end and the server is the back-end of the service. It is important to note that both of these entities are independent of each other. The server-side code (the API) and the client-side code can each be changed without affecting the other, as long as both continue to communicate in the same format.

3. Cacheable: The client should have the ability to store responses in a cache. This greatly improves the performance of the API.

4. Uniform Interface: This constraint indicates a generic interface to manage all the interactions between the client and server in a unified way, which simplifies and decouples the architecture.

5. Layered System: The server can have multiple layers for implementation. This layered architecture helps to improve scalability by enabling load balancing.

6. Code on Demand (optional): This constraint indicates that the functionality of the client applications can be extended at runtime by allowing a code download from the server and executing the code.

REST APIs may not be the best solution for everyone, but it is simple and good enough. That is why it is used so popularly nowadays