6.3REST APIs and data formats

The entry point for "operating the controller from a script" in the previous section is the REST API. A REST API reuses the very HTTP mechanism we use in browsers every day, to "read (GET)," "create (POST)," "update (PUT)," and "delete (DELETE)" device state. Most of the data exchanged is in JSON, a lightweight format. This section builds the basic etiquette of REST APIs and the ability to correctly read returned JSON, from the practical viewpoint of operating via API instead of CLI.

6.3.1REST API nature and CRUD/HTTP methods

• A REST API is an API style that points at resources (devices, configs, state) by URL over HTTP and operates on them with HTTP methods. It is stateless: the server retains no client session state between requests, so each request is self-contained, carrying the needed information (auth token, etc.) each time.
• CRUD (Create/Read/Update/Delete) maps to HTTP methods: Create=POST / Read=GET / Update=PUT (partial update=PATCH) / Delete=DELETE. Example: GET /api/v1/interfaces reads the state of all interfaces; POST /api/v1/vlans creates a new VLAN.
• A request carries headers (Content-Type: application/json, an auth token, etc.), and for create/update a body (a JSON payload). A GET usually has no body and identifies the target via the URL.

6.3.2Reading success/failure from HTTP status codes

• 2xx = success: 200 OK (read/update succeeded), 201 Created (new resource created). An automation script uses this code to decide to proceed.
• 4xx = client-side error: 400 Bad Request (malformed request), 401 Unauthorized (not authenticated), 403 Forbidden (insufficient permission), 404 Not Found (no such target). It points to what the requester must fix.
• 5xx = server-side error: 500 Internal Server Error, etc. The request may be valid but failed inside the server, and the requester's fix will not resolve it. Whether it is 4xx or 5xx changes where to look (your request vs. the server).

6.3.3Reading JSON (objects, arrays, data types)

• JSON is a lightweight data format representing an object as key:value pairs enclosed in { }. Values can be a string ("up"), a number (1500, unquoted), a boolean (true/false), null, a nested object, or an array.
• An array is an ordered list enclosed in [ ]. Example: "addresses": ["10.0.0.1", "10.0.0.2"] is a two-element string array. Elements are counted from index 0 (addresses[0] is "10.0.0.1").
• Distinguishing data types matters in practice: "enabled": true is a boolean, but "enabled": "true" is a string, and a script that mistakes the type will misjudge a condition. "mtu": 1500 is a number; "mtu": "1500" is a string.

Suppose you are writing a monitoring script and, for the controller's GET /api/v1/interfaces/GigabitEthernet0/1, the following JSON is returned: { "name": "GigabitEthernet0/1", "enabled": true, "mtu": 1500, "addresses": ["10.0.0.1", "10.0.0.2"], "description": null }. First you confirm the status code is 200 OK before proceeding to interpret the body (because 401 means an auth-token problem and 404 means that interface name does not exist—the isolation differs). The body is a single object ({ }), and the value of enabled is true without quotes, so it is a boolean—mistaking it for "true" (quoted = string) would create a bug where if enabled true is always false. mtu is 1500 without quotes, so it is a number usable in arithmetic. addresses is an array in [ ], where addresses[0] is "10.0.0.1" and addresses[1] is "10.0.0.2" (note counting from index 0). description is null, meaning "no value is set," distinct from an empty string "". If you want to disable this interface, the correct move is to send { "enabled": false } with an update (PUT), not a read (GET); a delete (DELETE) is a different operation that removes the interface configuration itself. This sequence—isolate success/failure by status -> read the JSON types and structure accurately -> operate with the method that matches your goal—is the foundation of operations that replace CLI with API.

6.3.4Section summary

• A REST API is stateless and HTTP-based, mapping CRUD to create POST / read GET / update PUT / delete DELETE
• HTTP status is 2xx success / 4xx client error / 5xx server error. Distinguish 401 (not authenticated) from 403 (insufficient permission), and 400 (malformed) from 404 (no such target)
• JSON consists of {} objects and [] arrays; read the string/number/boolean/null types accurately (true and "true" differ; arrays start at index 0)