REST API basics: methods, status codes, auth

A REST call is a method, a URL and a status code to read

A REST API exposes resources (devices, users, VLANs) at URLs and lets a client act on them with standard HTTP methods; the server answers with a status code, headers and usually a JSON body. The rule that settles most questions: the method says what you want done, the URL says to what, and the status code family says who is at fault, with 2xx meaning success, 4xx meaning the client’s request is wrong, and 5xx meaning the server failed. HTTP semantics are defined in RFC 9110; REST itself is a style on top, not a standard.

Follow one request from start to finish

The scenario: a script manages devices on a controller at api.example.net.

Step 1: authenticate. The script sends credentials once and gets a token, or uses an API key issued in a console. Every later call carries it in a header:

GET /v1/devices?limit=2 HTTP/1.1
Host: api.example.net
Authorization: Bearer eyJhbGciOi...
Accept: application/json

Basic authentication (RFC 7617) sends username:password base64-encoded, which is encoding and not encryption, so it is only acceptable over HTTPS. Bearer tokens are defined in RFC 6750. For how tokens are issued, see SSO, SAML and OAuth explained.

Step 2: read the response. A good response looks like this:

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://api.example.net/v1/devices?limit=2&after=d2>; rel="next"

{ "items": [ {"id": "d1", "name": "sw1"}, {"id": "d2", "name": "sw2"} ] }

Step 3: create something. POST /v1/devices with a JSON body and Content-Type: application/json. Success is 201 Created, and RFC 9110 says the new resource is identified by the Location header (or by the target URL if there is none).

Step 4: change it. PUT /v1/devices/d3 replaces the whole resource; PATCH changes part of it (PATCH comes from RFC 5789, not RFC 9110). Success is 200 with a body or 204 No Content without one.

Step 5: remove it. DELETE /v1/devices/d3, usually 204.

The same walk is the CRUD mapping the exams use: Create is POST, Read is GET, Update is PUT or PATCH, Delete is DELETE.

Idempotency decides what you may retry

RFC 9110 defines a method as idempotent if several identical requests have the same intended effect on the server as one. Of the standard methods, PUT, DELETE and the safe (read-only) methods are idempotent; POST and PATCH are not guaranteed to be. The spec’s practical consequence: a client may automatically repeat an idempotent request after a lost connection, but should not blindly repeat a POST, because it might create a second device.

Idempotent does not mean the response is identical: a second DELETE may return 404 because the resource is already gone, yet the end state is the same. The same idea reappears in infrastructure as code, where a playbook run twice should change nothing the second time.

Status codes: diagnose from the number

Two pairs cause most wrong answers: 401 versus 403 (who are you versus you may not) and 400 versus 422 (cannot parse versus parsed but invalid).

Pagination

Large collections are returned in pages, and the API tells you how to get the next one. There is no single standard. Offset pagination uses ?limit=100&offset=200; cursor pagination returns an opaque token (after=d2) and is stable when items are added during the walk; many APIs advertise the next page in a Link header (RFC 8288) or a next field in the body. The loop is always the same: request, process, follow the pointer, stop when there is none. A script that reads only the first response gets only the first page.

Which exams test this

How questions are built around it

Scenario questions hand you a symptom and a status code, then offer causes. The deciding words: “expired token” and “credentials” point to 401; “authenticated but not allowed” points to 403; “wrong path” to 404; “too many requests” to 429 and backoff; “first 100 of 450 records” to following pagination. For method questions, “create without specifying the ID” is POST, “replace entirely” is PUT, “change one field” is PATCH. Watch the trap in “which method is idempotent”: POST is the usual wrong option, and DELETE is the one people forget is idempotent. Reading JSON replies is covered in JSON vs YAML vs XML, and the model-driven alternative for devices is in REST, NETCONF and RESTCONF.

Practice questions

Go deeper

• RFC 9110, HTTP Semantics (methods in section 9, status codes in section 15)
• RFC 6750, Bearer Token Usage and RFC 8288, Web Linking
• Next on this site: Python for network engineers for the requests library, and the 200-901 cheat sheet.