An API (Application Programming Interface) is a software interface that allows two applications or components of applications to communicate with each other. They serve as a standard format for how the two applications can request and retrieve data, or request other services, in a way that both can understand even if they were written by entirely different people or are using different technologies (different programming languages).
APIs are essential not just for computer networking, but for the interconnection of all kinds of applications.
In Software-Defined Networking (SDN), APIs are used to communicate between management applications and the SDN controller via the Northbound Interface (NBI), and also for communications between the SDN controller and its managed network devices via the Southbound Interface.
The NBI typically uses REST APIs, and there are various options for Southbound APIs including NETCONF and RESTCONF.
CRUD
CRUD is a funny-sounding acronym for Create, Read, Update, Delete. These are all operations we can perform using REST APIs.
- Create operations are used to create new variables and set their initial values.
- Read operations retrieve the current value of a variable.
- Update operations change the value of an existing variable.
- Delete operations delete variables.
HTTP
HTTP (HyperText Transfer Protocol) uses verbs (also called methods) to perform various CRUD operations. REST APIs typically use HTTP as their application-Layer protocol for communications.
| Purpose | CRUD Operation | HTTP Verb |
|---|---|---|
| Create new variable | Create | POST |
| Retrieve value of variable | Read | GET |
| Change the value of variable | Update | PUT, PATCH |
| Delete variable | Delete | DELETE |
| ^[Mozilla has some decent documentation on HTTP verbs: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods] |
HTTP Request
When an HTTP client sends a request to an HTTP server it uses an HTTP header. That header includes:
- An HTTP verb
- A URI (Uniform Resource Identifier) indicating the resource to be accessed.
- Additional headers to pass more information to the server as needed
Example
An Accept header telling the server what types of data can be sent back to the client:
- Accept: application/json or Accept: application/xml
The HTTP header is encapsulated by the Layer 4 header (and Layer 3 & 2 headers) and forwarded.
Header Layout:
| IP Header | TCP Header | Verb | URI | Additional Headers | Data |
|---|
When a REST client makes an API call to a REST server, it will send an HTTP request. Technically, REST APIs don’t have to use HTTP for communication, but it is the most common choice.
HTTP Response
A server’s response to any given request will include a three-digit status code indicating the success or failure and other details of the request in the response message’s HTTP header.
The first digit of the status code indicates the class of the response:
- 1xx - Informational; the request was received and is being processed.
- 2xx - Successful; the request was received, understood, and accepted.
- 3xx - Redirection; further action required, e.g. if the URI for the requested resource has changed, this prompts the client to get the new URI to get the resource.
- 4xx - Client error; the request contains bad syntax or cannot be fulfilled, e.g. selecting a resource that doesn’t exist.
- 5xx - Server error; the server failed to fulfill an apparently valid request.
Some common examples of each response class:
- 102 Processing; indicates that the server has received the request and is processing it, but the response is not yet available.
- 200 OK; the request succeeded. If the request asked for a particular resource then it will be included in the body.
- 201 Created; the request succeeded and a new resource was created e.g. in response to a POST request.
- 301 Moved Permanently; indicated the requested resource has been moved, and the server indicates its new location.
- 403 Unauthorized; the client is not authenticated and will not be given a response. 1
- 404 Not Found; the requested resource couldn’t be found. You’ve probably seen this one before. If not, click here and you will.
- 500 Internal Server Error; the server encountered something unexpected and doesn’t know how to handle it.
REST APIs
REST (Representational State Transfer) APIs, also known as REST-based APIs or RESTful APIs, does not refer to any specific API, but rather describes a set of rules about how an API should (or can) work.
There are six constraints of RESTful architecture:
- Uniform Interface
- Client-server
- Stateless
- Cacheable or non-cacheable
- Layered System
- Code-on-demand (optional)
REST APIs use a client-server architecture. The client uses API calls (HTTP requests) to access the resources on the server. Because the client and server are completely separate, they can both change independently of each other. It is important that any such changes do not interfere with the API, or if they do that adequate changes are made on both the client and server so as not to break the interface.
REST API exchanges are stateless.2 This means that each API exchange is treated as a completely separate event; information about previous exchanges is not stored and not used to inform responses to new requests. This means (among other things) that if authentication is required, the client must re-authenticate with every new request it makes.
Note
REST APIs (usually) use HTTP, which in turn uses TCP as its Layer 4 protocol. TCP itself is stateful, however, that does not mean that HTTP or REST APIs can be considered stateful. The functions of these layers are largely separate.
REST APIs must support data caching. Caching means storing data for future use, especially storing data that is likely to be needed soon in an easily accessed place. For example, modern web browsers will cache elements of websites locally so they don’t have to retrieve the data from the server every time the page is loaded; this improves responsiveness for the client, reduces bandwidth consumed, and reduces the load on the server. REST APIs must support similar functionality.
Not all resources have to be cacheable, but those that are must be declared as cacheable.
Footnotes
-
In the Security topic of Authentication, Authorization, & Accounting, we explain the distinction between authorization and authentication. You could make an argument that HTTP error 403 Unauthorized should actually be named Unauthenticated. ↩
-
Funny that Representational State Transfer APIs are stateless… ↩