All APIs Are Not Created Equal

I recently wrote a job description for a network programmability engineer. One competency for the position is the ability to write code using the application programming interface (API) of devices of various vendors.

All networking vendors are promoting their programmability features and we continue to see interest from our leading customers on learning to program using these device APIs.

As the network programmability engineer begins to develop integrated solutions using device APIs, they will soon find that all APIs are not created equal.

Documentation is a critical component

Cisco APIC-EM uses Swagger (swagger.io), a simple yet powerful representation of the API from the web interface. One extremely useful feature is the "try it now" button, which executes the API against the server and illustrates the request URL, the resulting return code and the response body and header.

F5 appliances have a user guide, the iControl© REST User Guide, but they also implement a self-documenting feature. Each root module, a component of the F5 appliance, can be queried and returned as a list of URLs used to query or update the various aspects of the module. Normally the programmer would use a tool like Chrome Postman to issue a query and discover the structure.

Authentication methods vary

I recently wrote code to use the API from a Cisco IP phone to format and post the data to Phantom Cyber, which is a security-focused but generic automation platform. The Cisco phone implements no authentication. You simply point a web browser at the IP address of the phone and can retrieve statistics about the active or most recent call. Phantom uses a token, which first requires administrator access to obtain, and can be associated with a source IP address and easily revoked by the administrator. F5 appliances use basic authentication, a username and password sent with the request.

Creating versus modifying resources

The method used to create and update a resource through the API varies from vendor to vendor as well. For example, the Cisco APIC REST API will allow the network programmer to use the same verb (POST) and body of the request to create or update a resource. If it doesn't exist, it is created, if it does exist, it is updated. The F5 iControl, is a bit more restrictive, the verb POST creates a new object while a PUT or PATCH is used to update an existing configuration. Some aspects of the body of the request must be modified as well.

Learn the basics

To be effective as a network programmability engineer, learn the basics of programming to a REST API. Cisco DevNet is a good learning resource. Start by exploring the Cisco Webex teams APIs at developer.ciscospark.com and once you've learned how to program APIs, create a room, post messages, add members and interface with other network devices.