A reader sent me this question:

I am hearing a lot about API in reference to SDN. I do not have any software or programming background but would like to understand this API in practical way. Could you help me?

TL&DR: API is CLI for program-to-program communication

More seriously, API stands for Application Programming Interface – a definition how programs (or clients) could use a library (or a server). Sometimes it’s as easy as defining functions a program can call, the parameters those functions accept, and the acceptable values of those parameters.

For example, when a C program wants to open a file, it calls the open function, which accepts a file name, and the way the file should be opened (Could the program write into the file? Should the file be created if it doesn’t exist?).

It seems Cisco’s OnePK follows this path – it defines a large number of functions that a Java program can call to influence Cisco IOS behavior, either on the local device (if you somehow manage to run Java on a Cisco’s box) or on a device to which the Java program has previously connected using yet-another function call.

Client-server APIs usually use a request-response protocol, where the client encodes its function call into whatever protocol message, sends the message to the server, which executes the call, and returns the results of the function back to the client.

One of the most popular client-server API methods is REST, which encodes the parameters or function results in JSON (think: JavaScript) or XML format (both of them are pretty easy to parse in a computer program) and uses HTTP(S) as the transport protocol to exchange data between the client and the server.

For example, you can use REST API to configure an Arista switch. Instead of logging into the switch and typing show ip interface, your network configuration program could execute the following HTTP request:

Obviously there’s no need for the API to mirror the CLI functionality. The features available through the API could be totally different from the CLI commands, or a small subset of them. The API could also work on the control plane, or allow you to plug your code straight into the data plane (like F5 iRules).