API is the abbreviation of Application Programming Interface. Different Applications use APIs to communicate each other. In this communication, they learn the other application’s variables, modify variables, create new variables etc. In otehr words,many softwares can communicate over these APIs. So, in software development, working on APIs is a key duty. Beside classical coding activities,m a software developer also writes codes fort he communication with different applications. These codes can be written or can be taken from anywhere. There are different types of APIs. But here, we will focus on the mostb important one for Network Automation World. This is REST APIs. REST is the abbreviation of Representational State Transfer (REST). These tpye of APIs are also called REST-Based APIs or RESTfull APIs.
So, what are the main properties of REST APIs? Now, let’s explain REST APIs, REST-Based APIs properties one by one.
REST API Features
As all API types, REST APIs has also some features to define itself. What are these REST API Features? These six key features of REST APIs are given below:
- Layered System
- Code on Demand
- Uniform Interface
Now, let’s explain these REST API features one by one.
REST API Works with Client/Server model. The requester is the Client and the data source or the destination is the Server. This separates user interface concerns and the data storage concerns. By doing this, user interface portability is improved.
Let’s explain the operation of this Client/Server architecture.
As you can see above, firstly REST Client starts a REST Call. Then this Rest Call is received by the API of the REST Server and this API decides what to do. After that, REST Server replies to the REST Call.
You can also learn data serialization languages like JSON, YAML, XML that are used between REST Server and REST Client as an interpreter
Each API requests and replies are behaved separately independant from the previous and the future requests. The request message includes all the required information for the server to understand it. Server do not need to store any information.
REST API sytem follows a layered architecture. Each layer is responsible from a specific functionality. This type of architecture, make it easy to understand with less complexity.
This is the system which helps to minimize the server calls, improves quality and decrease response times. Here, the data within the response can be labeled as cacheable or non-cacheable. This is similar to your browser cache mechanism. To reduce processes and improve performance, web browser caches are sued. REST API Cache mechanism is also used to reduce processes and improve performance.
Code on Demand
REST APIs gives extra functionality to the client by dowmloading or executing any code or scripts.
This constraints defines the communication between client and server. There are four interface constraints.These are:
- Resource Identification
- Resource Manipulation
- Seld Descriptive Messages
HTTP Verbs (HTTP Methods) and CRUD Actions
APIs are used for the communciation between two applications as we have defined before. To provide this, APIs uses different protocols. REST-Based APIs use HTTP protocol fort his purpose. Because, HTTP is very similar to REST.
REST API uses the below four information parameter to identify and process each request:
- Verb (Method)
- Path (Endpoint)
- Body (Data)
So, what are these fields? Let’s explain one by one.
There are some common HTTP Verbs, HTTP Methods that are used by also REST APIs. These are:
Now, let’S explain the roles of these each HTTP Actions, HTTP Verbs.
GET : GET returns with the data that you request from the destination defined with URL.
POST : POST writes new data to the destination defined with URL.
PUT : PUT is used to update a data at the destination defined with URL.
DELETE : DELETE is used to delete any data at the destination defined with URL.
PATCH : PATCH modifies the data at the destination defined with URL.
HEAD : HEAD is similar to GET, returns with only Header information.
OPTIONS : OPTION returns with available methods for a specified resource.
These HTTP Methods are used for four main http actions; Create, Read, Update and Delete. These actions are showed with the abbreviation, CRUD.
- Create action is POST,
- Read action are GET, HEAD and OPTIONS,
- Update actions are PUTand PATCH,
- Delete action is DELETE.
Cisco DNA Center is the recent Network Automation Solution of Cisco. REST APIs are used with Cisco DNA Center in the Northbound Interface. As we have explained in Cisco DNA Center and SD-Access Lessons, APIs are used by developers to access Cisco DNA Center by scripting. With this Access, developers can do the actions create, modify, delete etc. on Cisco DNA Center. For example they can create a new VPN service, they can modify a new security policy, they can delete a network device from the network. All these actions can be done with REST APIs. The protocol used with REST APIs is HTTP. In other words, HTTP verbs are used for the actions. And the resorce that is defined in REST API is UNI part.
For developers and network engineers, REST API documentation is important. Before working with REST APIs on your entwork, you should check REST API documentation related with your project.
HTTP Request Message Structure
As we have explained before, REST API is a Client/Server protocol. So, as Client/Server protocol, HTTP is also used with REST APIs. Replies and requests in HTTP Client/Server mechanism includes a HTTP verb that shows the action of that HTTP message in HTTP header. Beside this header, there is also another part called URI (Uniform Resource Identifier) in HTTP message. Below, you can find the shape of this message.
Here, verbs are the HTTP Verbs as we have talk about before. With these HTTP Verbs, the action of the http message is determined. The other important part in this HTTP Header is URI (Uniform Resource Identifier). URI is the part that identifies the resource. You can find the parts of URI below:
As you can see above, the first part shows protocol, HTTPS. HTTPS is the decure version of HTTP. The second part is the Host Address and the other part is the Path or in other words it is Resource. At the end of URI, there is a Parameter or Query Part. Special parameters related with REST Call is defined here.
REST API Examples
We can do a lot of examples with REST APIs. Here, I will show you a couple of examples. For example to configure BFD globally, we can use the below REST API:
<bfdIpv4InstPol name=”default” echoSrcAddr=”220.127.116.11″ slowIntvl=”1000″ minTxIntvl=”150″ minRxIntvl=”250″ detectMult=”5″ echoRxIntvl=”200″/>
<bfdIpv6InstPol name=”default” echoSrcAddr=”34::1/64″ slowIntvl=”1000″ minTxIntvl=”150″ minRxIntvl=”250″ detectMult=”5″ echoRxIntvl=”200″/>
Or, to create a VLAN Range, we can use the below REST API:
<fvnsVlanInstP name=”<vlan_pool_name>” dn=”uni/infra/vlanns-[<vlan_pool_name>]-static” allocMode=”static”>
<fvnsEncapBlk name=”” descr=”” to=”vlan-25″ from=”vlan-10″/>
To configure DNS Service Policy, we can use the below REST API:
POST URL :https://apic-IP-address/api/node/mo/uni/fabric.xml
<dnsProv addr=”172.21.157.5″ preferred=”yes”/>
<dnsDomain name=”cisco.com” isDefault=”yes”/>
HTTP Status Codes
As we have mentined, HTTP Works with Request & Response Model. With this model, whenever a request is sent a response with a status code is recevied. These HTTP status codes has different meanings. There are various HTTP Status Codes in the range 100+ and 500+.
Let’s learn some of these HTTP status codes.
200+ status codes mean that the requiest is successfull. But there are some different meangs of different codes in the 200+ range. For example:
- 200 (OK) :200 (OK) status code means the request is successfully sent and the response include the requiested data.
- 202 (Accepted) :202 (Accepted) status code means the remote server is accepted the request but need extra actions to complete the request.
300+ status codes mean that the url is redirected. For example:
- 301 (Moved Permanently) :301 (Moved Permanently) status code means the url is permanently redirected to a new URL.
Client Request :
GET /index.php HTTP/1.1
Server Response :
HTTP/1.1 301 Moved Permanently
- 302 (Found) :302 (Found) status code means the url is temporarily redirected to the new URL given by the location header.
400+ status codes mean that the error is because of the Client (originator). For example:
- 401 (Unauthorized) :401 (Unauthorized) status code means the requester do not have the required privilege level for this request.
- 404 (Not Found) :404 (Unauthorized) status code means that the server cannot find the requested resource. This is generally a status code that is sent for broken links.
500+ status codes mean that the error is because of the Server (destination). For example:
- 500 (Internal Server Error) :500 (Internal Server Error) status code means that there is an unexpected error in destination Server, so it can not complete the request.
- 505 (HTTP Version Not Supported) :505 (HTTP Version Not Supported) status code means that the HTTP version of Request sent by the Client is not supported by the destination Server.