REST APIs and JSON

What a REST API is

REST (representational state transfer) is a style of API that uses ordinary HTTP, the same protocol your browser uses for web pages. Everything the API manages, such as a device, an interface or a VLAN, is a resource with its own address called a URI (uniform resource identifier), for example https://catalyst.example.com/dna/intent/api/v1/network-device. A program sends a request to that URI and gets a response, usually in JSON.

REST APIs are stateless: the server does not remember earlier requests. Every request must carry everything needed, including who you are (usually a token in a header). This makes the server simpler and easier to scale.

HTTP methods and CRUD

CRUD stands for create, read, update and delete: the four things you can do with data. Each maps to an HTTP method.

Status codes: how did it go?

Headers

Headers are extra lines of information sent with a request or response. Content-Type tells the other side what format the body is in, for example application/json. Accept says which format you want back. Authorization (or a product-specific header such as X-Auth-Token on Catalyst Center) carries your credentials or token. A token is a long random string the server gives you after you log in once; you send it with every later request instead of your password.

# 1. Log in once and get a token (curl asks for the password)
curl -s -X POST -u admin https://catalyst.example.com/dna/system/api/v1/auth/token

# 2. Send the token with every later request
curl -s -H "X-Auth-Token: $TOKEN" -H "Accept: application/json" https://catalyst.example.com/dna/intent/api/v1/network-device

JSON syntax

JSON (JavaScript Object Notation) is a text format for data that both people and programs can read. It has a few simple building blocks:

• Object: key and value pairs inside curly braces, like {"hostname": "SW1"}. Keys are always strings.
• Array: an ordered list inside square brackets, like [10, 20, 30].
• String: text in double quotes. Single quotes are not allowed.
• Number: 1500 or 2.5, with no quotes.
• true, false and null: written in lower case, with no quotes.

{
  "hostname": "SW-PUNE-01",
  "managementIp": "10.20.1.2",
  "reachable": true,
  "uptimeDays": 41,
  "location": null,
  "vlans": [10, 20, 99],
  "interfaces": [
    {"name": "GigabitEthernet1/0/1", "status": "up", "vlan": 10},
    {"name": "GigabitEthernet1/0/2", "status": "down", "vlan": 20}
  ]
}

To read this in Python, json.loads(text) turns the JSON text into dicts and lists. data["interfaces"][1]["status"] then gives "down". json.dumps(data) does the opposite and turns Python data back into JSON text.

JSON, XML and YAML

All three describe the same kind of structured data. JSON is compact and strict. XML uses opening and closing tags and is more wordy. YAML is the easiest for people to write, but its indentation must be exactly right, and it allows comments starting with #.