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
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 |
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.
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 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
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
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 |
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.
https://searchmicroservices.techtarget.com/definition/RESTful-API
No comments:
Post a Comment