As will be discussed below in the REST API section, this pretty well represents the nature of REST API being a “Northbound” API, with Apps speaking to the Controller using it.
However to begin with I want to completely re-iterate here what I’ve written in previous articles as you cannot practice typing / knowing this enough (at least for me), so please feel free to skip down to the REST API section (though there is some new deeper dive API information included below so might want to give it a once over!)
Review of API’s in general, and some deeper review of what makes them work
To review what an API is, it stand for “Application Program Interface”
- There are Internal API’s on a PC that allows software to interact
- There are IP Based (Network) API’s that allow Applications to communicate
- Multi-protocol, can be CLI over SSH, HTTP, SNMP, etc
- An API at its most basic is a piece of code written to allow two applications to talk
In the SDN World there are two specific API Types:
- Northbound APIs that Applications use to communicate with the SDN Controller
- Southbound APIs of the SDN Controller connecting to devices
- Commonly this communication will be over HTTP(S)
- API uses Client / Server model where whatever is requesting Data is the Client and the Device responsible for responding with Data is the Server, so App->Controller the App is the Client, for Controller->Network Device the Controller is the Client
- These APIs are considered a “Web Service API” which is NOT formatted as CLI
- Web Service APIs are delivered in URI or URL format to devices, URI = Uniform Resource Indicator and URL = Uniform Resource Locator (which is used to reach web pages via the Internet)
An example of a URI Address (These are different from Cisco SIP dialing URIs you might find in google) is : /dna/intent/api/v1/network-device/{id}/vlan
This URI would request VLAN information from a device by the DNA Center controller.
Web service APIs can perform the following functions:
- Add new data (create)
- Ask for data (read)
- Modify existing data (update)
- Destroy / erase data (delete)
Some common Web Service APIs are:
- SOAP (Simple Object Access Point)
- XML-RPC
- JSON-RPC
- REST
Some protocols like SOAP have a very distinct and strict rule set for communication.
Whereas REST is more Generic about how it works Architecturally, like the OSI it provides an outline of how Data must get from Point A to Point B, but it is not stuck on certain protocols / data formats being for transmission of the data.
REST (Representational State Transfer) API reviewed
This Architectural style for distributed hypermedia systems, developed by Roy Fielding in his 2000 dissertation.
This is by far the most widely used Web Service API in use today in terms of Controllers / Automation Tools, so the other APIs are good to know secondary but REST should be the focus for immediate studies!
REST API acts on “Resources” using HTTP verbiage that you may be familiar with already such as “GET” “PUT” “POST” “DELETE” – Going back to the 4 functions listed above that API’s generally execute.
REST API generally is used in the Northbound Direction as of this writing, as Applications will use this generally to talk to the Controller, where the Controller will use another API to talk to the network devices in the Southbound direction.
REST isn’t necessarily a stand alone API, but style of API (RESTful) described here!
Other API’s can be considered RESTful APIs, sharing the same generic architecture that REST APIs use, which if course must be a Web Service or communicate over the network.
This is the list of 6 conditions that makes an API RESTful:
- Uniform Interface – Every resource reachable should have a consist naming convention for all resources it can reach, and use common approaches to reach that information such as an HTTP GET for the requested data
- Uses Client- Server Model – We already know what this means from above^^
- Statelessness – Controllers send down instructions to devices, they execute them without thought, and forget the request immediately after executing it – There is no “stateful” relationship between the controller and devices per change
- Cacheable – Resources may be cahceable on Client / Server side, device must declare itself as cacheable, more a server usage attribute so not seen in Network RESTful API’s as much but needs to be known as part of the RESTful structure
- Layered System – Rest allows usage of using multiple servers to deploy the API, using one server say to host the API, another for storage, another server to authenticate data, etc
- Code on Demand (optional) – This is a more in-depth RESTful API function, but essentially REST API goes and executes code on a device, and the Application talking to the controller can ask it to return some other type of Code from the device (which I only really could see in a Server environment using REST API)
HTTP Verbs and CRUD!
What this discusses is really the Verb used by HTTP (GET, PUT, etc) and how it maps to the CRUD command database, so the following is a 1:1 mapping of HTTP:CRUD verbs:
HTTP | CRUD
Post – Create
Get – Read
Put – Update
Delete – Delete
CRUD = Create Read Update Delete which CRUD is used as Database Commands, though I am not sure if that is more Server specific, but wanted to get that noted somewhere.
Rest API Data Encoding
When creating RESTful API’s for devices to communicate, the HTTP GET verbiage data formatting must be the same (the URI used to ID objects and resources), so you must have a listing of all URI’s needed for the Application to perform tasks required of it.
REST APIs also strive for with their coding:
- Quick serialization and deserialization of objects (fast communication)
- A compact format for accessing data (minimal headers for fast comms)
- Minimize data transfer required
- Offer Broad Language Support
REST API’s typically encode data in either JSON or XML Format which will be dug into at length in another article, as this is still just reviewing our API’s themselves!
Tying together Cisco DNA Center and REST APIs
Cisco has created its own REST API called “Intent API” which will be a Northbound API for Controllers to communicate with Applications North of the controller, and having one standard “Cisco Proprietary” REST API will help with creation of Applications that need to talk with DNA Center Controllers.
To actually SEE the URI’s that are used for DNA Center REST API, so that developers have a place they can reference all the URI’s that must match for communication, click below:
DNA Center REST (Intent based) API
An interesting curveball to the Northbound / Southbound API concept
When DNA Center has to community horizontally with an ISE Controller, what direction is that, as its kind of on the same level as DNA Center / they work together:
The answer is Northbound. REST API’s are used between ISE talking to both the Controller APIC and the DNA Center Software itself, and is considered “Northbound” in its direction of APIs.
That is is for this one!
I am sure REST API talk will come up again at some point, however I feel this is a good foundation for the night on REST APIs specifically and how they operate, until next time!
The DEVNET GRIND! 