Characteristics of REST-Based APIs

What it is

A REST API lets one program talk to another over HTTP by sending requests for resources and receiving structured answers.

An API (application programming interface) is a defined way for one piece of software to talk to another. Instead of a person typing commands, a program sends a request and receives a structured answer.

REST (Representational State Transfer) is the most common style of web API. It runs over HTTP or HTTPS, the same protocol that web browsers use, and it treats everything as a resource that has an address. Network controllers, cloud platforms and many devices offer REST APIs.

REST APIs follow a few design rules:

• Client-server: the client sends requests, and the server answers.
• Stateless: each request carries everything the server needs. The server does not remember earlier requests.
• Uniform interface: resources are accessed in the same standard way, using standard HTTP methods.
• Cacheable: responses can say whether they may be stored and reused.

How it works

The client sends a request made of a method, a URI, headers and an optional body, and the server answers with a status code and usually a body.

The request

A REST request has several parts:

• a method, such as GET
• a URI that identifies the resource, such as /api/v1/devices
• headers, which carry extra information such as the data format and the credentials
• an optional body, which holds the data being sent

A URI has a path to the resource, and it can have a query string to filter the result, for example /api/v1/devices?limit=10. The server's address is given separately, in the host part of the web address.

HTTP methods and CRUD

Most data operations are described with the acronym CRUD: create, read, update and delete. Each one matches an HTTP method.

GET is only a read, and should not change anything. PUT and PATCH both mean update, but PUT sends the whole object, while PATCH sends only the changed fields.

The response and status codes

The server answers with a status code and, usually, a body. The first digit tells you the category.

• 2xx: success. 200 OK means the request worked. 201 Created means a new resource was made. 204 No Content means success with nothing to return.
• 3xx: redirection.
• 4xx: client error. 400 Bad Request means the request was malformed. 401 Unauthorized means credentials are missing or wrong. 403 Forbidden means the user is known but not allowed. 404 Not Found means the resource does not exist.
• 5xx: server error. 500 Internal Server Error means the server failed.

A way to remember: 4xx is the client's fault, and 5xx is the server's fault.

Authentication

An API must know who is calling. The common methods are:

• Basic authentication: the user name and password are encoded and sent in a header with each request. The encoding is not encryption, so basic authentication is safe only over HTTPS.
• Token (bearer) authentication: the client first logs in, and receives a token. It then includes the token in later requests. The token usually expires, which limits the damage if it is stolen.
• API key: a fixed secret string sent with each request, often in a header.
• OAuth 2.0: a framework in which a user lets one application act for them with another service, without giving away their password. The application receives a limited-access token.

Many network controllers use the token pattern: a first request with basic authentication returns a token, and later requests send that token in a header. Cisco Catalyst Center works this way, with the token carried in the X-Auth-Token header.

Always use HTTPS, because it encrypts the request, including the credentials and the data.

Data encoding

The body of a request or response needs a format. The most common are:

• JSON: light and easy to read, and the usual choice for REST APIs.
• XML: older and more verbose.
• YAML: easy for people to write, and common in configuration files.

Headers say which format is in use. Content-Type tells the server what the client is sending, and Accept tells the server what the client would like back.

An example

Reading a list of devices from a controller might look like this:

GET /api/v1/devices?limit=2
Accept: application/json
X-Auth-Token: TOKENVALUE

A possible response body:

{
  "response": [
    { "hostname": "SW1", "reachable": true },
    { "hostname": "SW2", "reachable": true }
  ]
}

The status code would be 200. To add a device, the client sends a POST with a JSON body, and a successful reply is usually 201.