APIs and REST: northbound, southbound, verbs and response codes
The CLI is scriptable but error-prone, slow at scale and changes between versions; an API lets software talk to software. A controller's northbound API faces the applications and people that manage the network; its southbound API pushes changes to devices. Read an exchange by its verb, resource, headers, status code and JSON body.
By Arif, founder of Daveth · Updated
The full 8 min walkthrough is in Daveth Pro (Network). See what the plan opens
What this page answers
What is the difference between a 401 and a 403 response?
401 Unauthorized means no valid credentials for the resource, and the WWW-Authenticate header says how to authenticate. 403 Forbidden means the request was understood, and refused: the caller is known but not allowed. Read it in “4.1 Why APIs, and which way they face”
What are northbound and southbound APIs?
A controller's northbound API faces up, toward the applications, the GUI and scripts that manage the network; its southbound API faces down, pushing changes to routers, switches and access points. Read it in “4.1 Why APIs, and which way they face”
What do the common REST status codes mean?
200 OK, it worked; 201 Created, a new resource was made; 400 Bad Request, the request itself was unusable; 401 Unauthorized; 403 Forbidden; 404 Not Found. Read it in “4.1 Why APIs, and which way they face”
4.1 Why APIs, and which way they face
A script gets 401 Unauthorized on a GET to the device list. Another gets 403 Forbidden on a DELETE. Which one has a bad password? Keep it for section 4.3.
The CLI is well known and scriptable, but the guide names misconfiguration as its biggest flaw, with human error behind most outages; it's also hard to scale, runs one command at a time, and its syntax changes between versions and platforms. An API, an application programming interface, lets software talk to software instead. It works like a waiter in a restaurant: you don't walk into the kitchen, you give a request in an agreed form and get a plate back.
A controller has two sides. Its northbound API faces up, toward the applications and people that manage the network: the GUI and your scripts use it. Its southbound API faces down, pushing changes to routers, switches and access points. Think of it as a building with a front entrance for visitors and a dispatch bay sending goods out: the same building, different doors, different traffic. This lesson and 09-3 use northbound REST APIs.
The guide's case against the CLI boils down to "people type things wrong", which is exactly how many devices you'd like to change by hand on a Friday night.
A RESTful API uses HTTP's methods to read and change data, which gives a consistent way to work with many vendors' APIs. The URL names a resource and the method says what to do with it, like the address on a letter against the instruction inside it: the same resource can take several methods. (The guide says every change or poll "has a unique URL", which is true of the method and URL together, not of the URL alone.)
| Method | RFC 9110 / 5789 | The guide's use case (Table 28-3) |
|---|---|---|
| GET | "requests transfer of a current selected representation" of the resource | viewing a website |
| POST | asks the resource to process what's sent "according to the resource's own specific semantics" | submitting login credentials |
| PUT | asks that the resource "be created or replaced" with what's sent | updating an NTP server |
| PATCH | applies "partial modifications to a resource" | adding an NTP server |
| DELETE | removes the resource's association with its URL | removing an NTP server |
The guide's word for PATCH, "appends", is one kind of partial change. In the demo API, POST to the list creates a new item resource with its own URL; PUT replaces the whole list; PATCH changes part of it, adding one server. It's a bit like the difference between opening a new file for one customer, rewriting the whole customer list, and adding one line to it. CRUD, create, read, update, delete, is the same idea from the database side; mapping POST to create, GET to read, PUT and PATCH to update and DELETE to delete is this lesson's reading of the guide's two tables, its HTTP verbs and its CRUD operations, not the guide's statement.
Table 28-4 files "updating a customer's home address" under CREATE, which is one way to make sure every house move gets a brand-new customer.
Every reply starts with a three-digit status code, and the first digit is the class: 2xx the request was "successfully received, understood, and accepted", 4xx it "contains bad syntax or cannot be fulfilled", 5xx the server "failed to fulfill an apparently valid request". It works like the first word of a doctor's report: before the details, you know whether to relax. The codes to know, with the guide's six and one more:
| Code | Phrase | What it tells you |
|---|---|---|
| 200 | OK | it worked; data may be in the body |
| 201 | Created | a new resource was made; Location names it |
| 400 | Bad Request | the request itself was unusable: a body that isn't JSON, or a missing field |
| 401 | Unauthorized | no valid credentials for this resource; WWW-Authenticate says how to authenticate |
| 403 | Forbidden | understood, and refused |
| 404 | Not Found | nothing at that URL, or the server won't say there is |
| 405 | Method Not Allowed | the resource exists but doesn't take this method; Allow lists what it takes |
That answers section 4.1. In the token pattern the password is only sent to the token request, so a 401 there means a bad password; a 401 on a later GET means the token is missing, invalid or expired. A 403 means the request was understood and refused: here, the token may only read. It's like a hotel front desk: 401 is "I can't accept that key card", 403 is "your key card works, but not on the penthouse floor."
You know what a read-only token gets for a DELETE. Predict before D1: the same token sends the DELETE to the typo, /api/v1/ntpp. Is it 403 or 404?
D1

It's 404. This API checks the path first, so the token is never even looked at; put the URL right and it's 403 Forbidden: the token is accepted and may only read. Send a DELETE to the whole list and it's 405, with Allow: GET, POST, PUT, PATCH. The body says more than the code: every error here carries a JSON message, and a success carries the data. In Python's requests library (reading Python is 09-7's), response.ok is True when raise_for_status() wouldn't raise, which for real status codes means below 400; raise_for_status() turns a 4xx or 5xx into an exception.
| What you see | Proves | Doesn't prove |
|---|---|---|
200 OK | the server handled the request without an error | that the body holds what you wanted: read it |
201 Created | a resource was created (at Location) | that devices are configured: that's the controller's southbound job; some APIs answer writes with 202 Accepted, "accepted for processing" but not completed (09-3) |
401 Unauthorized | no valid credentials for the resource | which: a wrong password, an expired token or a missing header |
403 Forbidden | the server understood and refuses | who you are, or that credentials were even the issue |
404 Not Found | nothing the server will show at that URL | that the path is wrong: the item may be gone, or hidden from you |
405 Method Not Allowed | the resource doesn't take that method | that the URL is wrong: it exists |
400 Bad Request | the server couldn't use the request | which part: read the error body |
403 is the most polite no on the internet: the server confirms it understood you perfectly before refusing anyway.
Catalyst Center doesn't take your password on every call. You POST once to its token API with basic authentication, get a token back in the JSON body, and send that token in an X-Auth-Token header on the calls that follow. A token works like a festival wristband: you show your ticket once at the gate, and the wristband gets you into each stage until it expires. The guide says to think of the token as a hash of your credentials, but its own example is a JSON Web Token whose middle part decodes to readable JSON. That token carries an expiry time, exp, 2018-03-19 22:07 UTC, and a list of roles, which is how a server can know to answer 403. (09-2 opens a token up; 09-4 covers what it means for security.)
Headers travel with the request, like the label on a parcel, while the body is what's inside. Figure 28-9's GET shows Content-Type: application/json and X-Auth-Token, and also a greyed Authorization: Basic ... row: Postman's leftover from the Basic Auth set-up, which the token pattern doesn't need. Content-Type gives the media type of the representation a message carries; this GET carries no body, so the header has nothing of its own to describe. X-Auth-Token is a header of its own, not a content type, whatever the quiz answers' wording. And that Basic value isn't encrypted: decoded, it's devnetuser:Cisco123!. RFC 7617 says Basic is not a secure method "unless used in conjunction with some external secure system such as TLS"; 09-4 takes that up.
Continue the lesson
The whole lesson, with its drawings and its questions. The rest of this section and 9 more after it.


