Describe characteristics of REST-based APIs (authentication types, CRUD, HTTP verbs, and data encoding)

What an API is

An API (application programming interface) is a contract that says “if you send me a request in this format, I will do this and reply in that format.” APIs let one program use the features of another without needing to understand its internals. Modern network controllers, cloud platforms, and even individual IOS-XE devices expose APIs so that scripts can manage them.

What makes an API “RESTful”

REST (Representational State Transfer) is not a protocol; it is an architectural style described by Roy Fielding in 2000. An API that follows REST’s rules is called RESTful. REST APIs almost always run over HTTP or HTTPS, use URIs to name the things being managed (called resources), use the standard HTTP methods to say what to do, and carry data in a format like JSON or XML. The six REST constraints appear on the exam as “characteristics of REST APIs.”

Anatomy of a URI

A REST resource is identified by a URI (Uniform Resource Identifier). The exam expects you to name the parts.

https://catalyst.example.com:443/dna/intent/api/v1/network-device?hostname=SW1
\___/   \______________________/\_______________________________/ \__________/
scheme          authority                    path                    query
(protocol)  (host and optional port)     (which resource)        (parameters)

• Scheme: the protocol, http or https.
• Authority: the hostname or IP address, optionally with a port (:443). Sometimes user credentials appear here too, but that is discouraged.
• Path: identifies the resource, for example /dna/intent/api/v1/network-device. Paths often include an API version (v1).
• Query: optional parameters after a ?, joined with &, used to filter or page results (?hostname=SW1&limit=10).
• The parts before the path (scheme://authority) are sometimes called the URL base, and the path plus query is called the resource or endpoint. (Technically a URL is a type of URI that includes the location; on the exam the terms are used interchangeably.)

CRUD and the HTTP verbs

Nearly every management task can be expressed as one of four operations, abbreviated CRUD: Create, Read, Update, Delete. REST maps each of these to an HTTP method (verb).

Idempotent means doing the operation several times has the same result as doing it once. Reading a VLAN list ten times does not change anything; deleting VLAN 30 five times leaves you with the same result as deleting it once (it is gone). Creating a VLAN five times with POST could create five objects, so POST is not idempotent. This word also appears in the Ansible and Terraform section.

HTTP headers

An HTTP request and response both carry headers, which are key/value lines that describe the message. The ones that matter for REST APIs:

HTTP status codes

The server’s response starts with a three-digit status code. The first digit tells you the class; the exact codes below are the ones to memorize.

Authentication types

Because REST is stateless, every request must prove who the client is. The common methods:

Data encoding: JSON, XML, and YAML

The body of a REST request or response has to be in a format both sides understand. Three text formats dominate.

The same data in all three formats:

JSON:
{
  "hostname": "SW1",
  "vlans": [10, 20],
  "managed": true
}

XML:
<device>
  <hostname>SW1</hostname>
  <vlans>
    <vlan>10</vlan>
    <vlan>20</vlan>
  </vlans>
  <managed>true</managed>
</device>

YAML:
hostname: SW1
vlans:
  - 10
  - 20
managed: true

Notice that YAML uses indentation (spaces, never tabs) to show structure, a dash for each list item, and does not require quotes around simple strings. XML wraps every value in an opening and closing tag. JSON uses braces for objects and square brackets for lists (section 6.7 covers JSON in depth).

A complete REST example

Here is what a request to Cisco Catalyst Center’s northbound API looks like. First the client gets a token, then it asks for the device list.

POST /dna/system/api/v1/auth/token HTTP/1.1
Host: catalyst.example.com
Authorization: Basic YWRtaW46Q2lzY28xMjM=
Content-Type: application/json

--- response ---
HTTP/1.1 200 OK
Content-Type: application/json

{ "Token": "eyJ0eXAiOiJKV1QiLCJhbGciOi...(truncated)" }

--- second request ---
GET /dna/intent/api/v1/network-device HTTP/1.1
Host: catalyst.example.com
X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOi...(truncated)
Accept: application/json

--- response ---
HTTP/1.1 200 OK
Content-Type: application/json

{
  "response": [
    {
      "hostname": "CORE-SW1",
      "managementIpAddress": "10.1.1.1",
      "platformId": "C9300-48P",
      "reachabilityStatus": "Reachable"
    }
  ],
  "version": "1.0"
}

The same request in Python using the popular requests library (you will not be asked to write this, but seeing it helps the concepts stick):

import requests

url = "https://catalyst.example.com/dna/intent/api/v1/network-device"
headers = {"X-Auth-Token": token, "Accept": "application/json"}
resp = requests.get(url, headers=headers, verify=False)
print(resp.status_code)          # 200
for dev in resp.json()["response"]:
    print(dev["hostname"], dev["managementIpAddress"])