Sunday, July 8, 2018

REST API 101

“A RESTful API -- also referred to as a RESTful web service -- is based on representational state transfer (REST) technology, an architectural style and approach to communications often used in web services development.”

Users can make HTTP - GET, PUT, POST, PATCH & DELETE requests to a device which support REST API and interact with the device. So before sending the REST requests to the device, we will need to have the instruction from the device vendor and understand the data structure/ format in the request and response. The data body exchange from local and remote system are in JSON format.

  • REST Request methods
First of all, let's talk about the standard Request methods. There are 5 major types of request method in REST: GET, PUT, PATCH, POST & DELETE.

GET – retrieves values for specified object

Most of time, GET request is the first call make from user to the device to obtain the specific information. For example, if you want to know interface details of a firewall, you can make a GET call to the firewall which support REST calls. Then obtain the interface name, duplex, speed, description, IP/mask etc.

The following example is a GET call. We can see there are 3 key components in the GET call. Basically they are the key components in all types of REST calls.

Request method: GET
Request URI:
Host:

Click to expand
PUT – Update the value for an existing object in the remote system

As explained above, PUT will update the object values. If the object does not exist in the remove system, an error code “404” will be returned.


PATCH – Applies a partial update for the remote object

A new REST user would be confused by PUT and PATCH because both of them can update the object values. However, if you want to use PUT, you will need to provide the full data structure of the object in the PUT call. And if you want to use PATCH, you only need to provide the data you want to update.

For example, if you want to update the IP address of the device and you want to use the PUT call, then you will have to provide not only the new IP address, but also all other settings in the interface data structure such as description, duplex, speed etc.

But if you want to use the PATCH call, then you will only need to provide the update IP address information. The updated information will be provided in the “body” field of the PATCH call.


POST – creates a new object with the provide values

POST call is used to create new object in the system. The body of the POST call will contain the values of this new object.

DELETE – remove the specified object

DELETE call is very self-explanatory. It can delete the specified object


  •  REST return codes
Once we make a REST request call to the server, we will expect a return message from the server. This return message will contain a code. Now let’s describe the meaning of these return codes.

Code
Description
20X
Two-hundred series code are successful return codes
200 OK
Request successful (standard return code)
201 Created
Request completed
202 Accepted
Request accepted, but processing not completed.
204 No Content
Request successful, but no content is returned
40X
Four-hundred series code caused by a client-side error
400 Bad Request
Invalid query parameters such as unrecognized parameters or invalid values
404 Not Found
The provided URI does not patch any existing resource
405 Method not Allowed
The request is not allowed on the specified object
5XX
Five-hundred series code indicates a server-side error

  •      Tools to make REST Calls
In the above post, we talked about the REST request and response. But how can we make these REST calls. There are many tools can help us to do that. The most famous one is POSTMAN application.

POSTMAN is a handy tool which allow us to make REST call by define every field in the call such as URI, Host, Body, method, authenticate type etc.



Click to expand
Postman can be downloaded from the following link:

https://www.getpostman.com/

If you don’t want to install the application but still want to play with the REST calls, you can install the REST Client Firefox add-on. It’s a lightweight method to enable you to consume the RESTful web services.

https://addons.mozilla.org/en-US/firefox/addon/restclient/



Click to expand
However, if you want to do programmable REST control to the device, a programmable language is required. Python or Ansible are your best friends then. 

In conclusion, REST is a very powerful tool to interact with remote system in the network. In the networking world, it’s also become more and more important. Although the data structure in JSON are vendor specified, the message formats are the same. So if we understand how to request and manipulate the JSON data in REST, we can easily control any of the systems no matter which vendors they are from.

In this blog, I have a post series which describe how to useAnsbile to interact with Cisco Fire Power Management Center with REST.


Reference:

https://searchmicroservices.techtarget.com/definition/RESTful-API



No comments:

Post a Comment

NSX Load Balancer "Application Rules" Examples:

Load Balancing is one of the features provided by the NSX Edge Services Gateway (ESG). It can provide L7 Load Balancing by utilizing the HA...