Module 7.2 35 minIntermediate

REST APIs, JSON, and YAML

Modern network devices expose REST APIs returning JSON. Configuration as code lives in YAML files. This chapter teaches the bare minimum to read and write both, plus a worked REST GET against a NetForge-like device.

Course plan — preview

What you'll learn

  • Read and modify a small JSON document.
  • Read a YAML file and understand its mapping/list syntax.
  • Identify HTTP verbs and status codes used in REST.

REST in one paragraph

REST = HTTP verbs against resources. GET retrieves, POST creates, PUT replaces, PATCH updates a part, DELETE removes. The response is usually JSON. Status codes follow HTTP: 2xx success, 3xx redirect, 4xx client mistake (401 = auth, 404 = missing), 5xx server error.

The exhibit is a RESTCONF request: REST applied to a network device's data model. It reads one interface, GigabitEthernet0/1, from router R1. The path names the model (ietf-interfaces), the list (interface) and the entry; the slash inside the interface name is written %2F so it is not read as a path separator. The reply is 200 OK with the interface as JSON.

A RESTCONF GET and the device's reply
GET /restconf/data/ietf-interfaces:interfaces/interface=GigabitEthernet0%2F1 HTTP/1.1
Host: r1.example.net
Accept: application/yang-data+json
Authorization: Basic <base64>

HTTP/1.1 200 OK
Content-Type: application/yang-data+json

{
  "ietf-interfaces:interface": [
    {
      "name": "GigabitEthernet0/1",
      "type": "iana-if-type:ethernetCsmacd",
      "enabled": false,
      "ietf-ip:ipv4": {
        "address": [
          { "ip": "10.0.1.1", "netmask": "255.255.255.0" }
        ]
      }
    }
  ]
}
A GET on one list entry still returns a list. The interface sits inside square brackets, under its module-qualified name ietf-interfaces:interface, so a script must take element [0] of that array before it can read a key such as enabled.

JSON essentials

Curly braces are objects (key-value pairs). Square brackets are arrays. Strings are quoted. Numbers and booleans are not. JSON is what most APIs return.

JSON has exactly six kinds of value: object, array, string (always in double quotes), number, the literals true and false, and null. Keys are always strings. The order of keys inside an object carries no meaning, while the order of an array's elements does — which is why an array can be indexed by position and an object cannot.

A router described in JSON
{
  "hostname": "R1",
  "interfaces": [
    { "name": "Gi0/0", "ip": "10.0.0.1", "prefix": 24, "up": true },
    { "name": "Gi0/1", "ip": "10.0.1.1", "prefix": 24, "up": false }
  ]
}

11 more sections in this chapter, plus a 4-question quiz.

Course plan

Modules 2–8 are part of the Course & Lab Pass and All-Access Max — start with a free account

You can see the title, summary, learning objectives and the opening sections. The rest of this chapter, like all of modules 2–8, comes with the Course & Lab Pass and All-Access Max. A free account opens Module 1: How Networks Work end-to-end and saves your labs — start there, no card required.

  • Read every chapter in Module 1 — How Networks Work
  • Save labs of up to 5 devices
  • Save up to 3 topologies
  • See the full course syllabus + chapter titles

Free account · no card required · compare plans any time