API Styles: REST, RPC, Synchronous and Asynchronous

What it is

An API style is the design approach that decides how a client asks for work and how the answer comes back.

Two styles dominate: REST, which is built around resources, and RPC, which is built around actions. Separately, a call can be synchronous or asynchronous, depending on whether the client waits.

Knowing the difference helps you read API documentation and predict how a call will behave.

How it works

REST and RPC describe what you ask for, and sync or async describes when you get the answer.

REST

REST stands for Representational State Transfer. It models the system as resources, each with its own address, and it uses standard HTTP methods to act on them.

REST follows a set of constraints:

• Client and server are separate. Each can change without breaking the other.
• Stateless. Every request carries all the information needed, and the server keeps no client session between calls.
• Cacheable. Responses can say whether a client may reuse them.
• Uniform interface. Resources have addresses and are handled with the same few methods.
• Layered. Proxies and load balancers can sit between client and server.

A REST call to read a device looks like this.

GET /v1/devices/42 HTTP/1.1
Accept: application/json

RPC

RPC stands for Remote Procedure Call. The client calls a named function on the server, as if it were a local function, and passes arguments.

RPC endpoints are named after actions, such as getDevice or restartInterface. Familiar RPC forms are XML-RPC, JSON-RPC and gRPC. SOAP is a related XML based protocol that sends structured messages, and the Unified Communications Manager AXL interface uses it.

A JSON-RPC style request names a method and its parameters in the body. Cisco NX-OS can accept commands this way through NX-API.

[
  {
    "jsonrpc": "2.0",
    "method": "cli",
    "params": {"cmd": "show version", "version": 1},
    "id": 1
  }
]

For this form NX-API expects the content type application/json-rpc.

REST compared with RPC

Synchronous calls

In a synchronous call, the client sends a request and waits for the response before it does anything else. The result comes back on the same connection.

This is simple and works well when the server answers quickly. A slow operation blocks the client until it finishes or times out.

Asynchronous calls

In an asynchronous call, the client does not wait for the final result. The server accepts the request, says that it is working on it, and the result comes later.

There are two common ways to get the result:

• Polling. The server returns a task ID, often with status 202. The client checks a task address until the work is done.
• Callback. The client registers a webhook, and the server sends the result when it is ready.

Cisco Catalyst Center works in this way for many write operations. It returns a task ID, and you read the task to learn whether it succeeded.

response = requests.post(url, headers=headers, json=payload)
task_id = response.json()["response"]["taskId"]

task = requests.get(
    BASE_URL + "/dna/intent/api/v1/task/" + task_id,
    headers=headers,
)
print(task.json()["response"]["progress"])

Asynchronous design suits long running work, such as a software upgrade on many devices.

Asynchronous code in Python

The word asynchronous is also used for program design. Python's asyncio library and the async and await keywords let one program start several slow calls and wait for them together. That is a separate idea from an API that returns a task ID, though the goal is similar.