REST APIs
Authentication types, CRUD and HTTP verbs, status codes and data encoding for REST-based network APIs.
Verbs and CRUD
REST APIs expose resources as URLs manipulated with standard HTTP verbs — stateless request/response, usually JSON-encoded bodies. Network controllers (and cloud services) expose northbound REST APIs so tools can read and change state without CLIs.
HTTP verbs → CRUD
| Verb | CRUD | Effect |
|---|---|---|
| GET | Read | Retrieve a resource — safe by contract (though access is still logged server-side) |
| POST | Create/process | Submit data for the resource to process — commonly creates a subordinate resource |
| PUT | Create or replace | Place the resource at the target URI — replaces it if it exists |
| PATCH | Update (partial) | Modify specified fields |
| DELETE | Delete | Remove the resource |
Status codes and authentication
Status code families
| Range | Meaning | Examples |
|---|---|---|
| 2xx | Success | 200 OK, 201 Created, 204 No Content |
| 3xx | Redirection | 301 Moved, 304 Not Modified |
| 4xx | Client error | 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found |
| 5xx | Server error | 500 Internal Server Error, 503 Unavailable |
Authentication types
| Type | How it works |
|---|---|
| Basic auth | Base64-encoded user:pass header — only over TLS |
| Token/API key | Pre-issued key sent in a header — lifetime set by the issuing service |
| Bearer token / OAuth2 | Token obtained from an auth flow — lifetime depends on the service, not the format |
| Certificates | Client TLS certificate identity |
- Call
- GET /api/v1/devices returns 401
- 401 = authentication problem — the token is missing, expired, or malformed.
- Not 403 (authenticated but forbidden) and not 404 (wrong URL).
- Fix: obtain a fresh token and resend with the Authorization header.
Status codes are the API's error report — read them before debugging anything else.
Encoding and exchange
Requests and responses carry media types: Content-Type: application/json for the body you send, Accept: application/json for the format you want back. Encoding is the wire format of that body — JSON is dominant; XML (and YAML for humans) also appear.
POST /api/v1/devices HTTP/1.1Create under the devices collection.Authorization: Bearer <token>Credential on every request.Content-Type: application/jsonBody encoding declared.{"hostname": "sw1", "site": "branch-7"}JSON payload.HTTP/1.1 201 CreatedServer confirms creation.Location: /api/v1/devices/sw1Where the new resource lives.Read a resource with curl — Shell
Any client OS
curl -s -H 'Accept: application/json' -H 'Authorization: Bearer <token>' https://controller/api/v1/devices
curl -i -s -H 'Accept: application/json' -H 'Authorization: Bearer <token>' https://controller/api/v1/devices
- 200 + JSON body = success.
- 401/403 = credential issues; 404 = wrong resource path.
- Use lab/sandbox endpoints only — never post real credentials in examples.
Read-only verification commands.
Verification
Common mistakes
- Using PUT where PATCH is meant — PUT replaces the whole resource and can wipe unspecified fields.
- Ignoring status-code families — 4xx means fix your request; 5xx means the server has a problem.
- Sending credentials over HTTP — Basic auth is only safe inside TLS.
- Assuming GET can change state — it's defined safe/idempotent by contract.
Observation: Previously-working script now returns 400 Bad Request on every POST.
- Payload schema changed — missing/renamed required field
- Wrong Content-Type header — body not parsed as JSON
- Malformed JSON in the request body
| Check | Indicates |
|---|---|
| Log the request shape with the Authorization header and sensitive fields redacted | A malformed payload shows immediately — never log bearer tokens or secrets. |
| API response body | 400s usually carry the validation error detail — though 403/404 can also hide existence for authorization reasons, not just wrong URLs. |
| Replay a known-good minimal payload against an authorized sandbox | Splits schema drift from serialization bugs — replaying POSTs against live endpoints creates side effects. |
Correction: Align payload and headers with the API contract.
The same call returns 2xx with the expected body.
Related resources
Sources
- Cisco CCNA 200-301 v1.1 Exam Topics (official PDF) — reviewed 2026-11-02
- RFC 9110 — HTTP Semantics — reviewed 2026-11-02
Targets CCNA 200-301 v1.1 objectives. Supplemental blocks are labeled beyond exam scope.