2.1Constructing REST API requests

Working with APIs is not about memorizing a list of methods; it is about reading the API docs and assembling the correct HTTP request that accomplishes your task. Even for the same goal of "get the list of devices," the endpoint URL, required headers, authentication scheme, and needed parameters differ per API, and getting any one of them wrong makes the request fail. This section nails the parts of a request and the common authentication schemes (Basic, API key, Bearer token), building the eye to pinpoint where your request diverges from what the docs require.

2.1.1Anatomy of a request

• The HTTP method expresses the kind of operation: GET (retrieve, no side effect), POST (create), PUT (replace the whole resource), PATCH (partial update), DELETE (remove). If the docs say "create a new resource" you use POST; if they say "change only some fields of an existing one" you use PATCH—choose the method from what you want to do.
• The endpoint (URL) locates the resource, with the path tail or query narrowing the target, e.g., GET https://api.example.com/v1/devices?limit=50. Query parameters (?limit=50&offset=0) handle filtering/paging, while the request body (usually JSON) carries the data payload for POST/PUT/PATCH. GET normally has no body.
• The headers carry request metadata: Content-Type: application/json declares the format of the body you send, Accept: application/json states the response format you want, and Authorization carries credentials. Forgetting Content-Type when sending a JSON body often yields 400 Bad Request or 415, because the server cannot interpret the payload.

2.1.2Authentication schemes

• Basic authentication sends username:password base64-encoded as Authorization: Basic <base64>. It is simple, but base64 is encoding, not encryption, and is trivially reversible—so use it only over HTTPS (TLS). Do not mistake base64 for an "encrypted, safe" value.
• An API key is an issued secret string placed where the docs specify—either a header (e.g., X-Api-Key: <key> or Authorization) or a query parameter (e.g., ?api_key=<key>). The crux is to follow the exact location and name the docs prescribe; putting a header-required key in the query, or misspelling the key name, are typical failures.
• A Bearer token is obtained by authenticating first (OAuth being the classic flow), then sent on each call as Authorization: Bearer <token>. Tokens have an expiry; once expired you get 401 and must re-obtain (refresh) one. Many Cisco DevNet APIs (e.g., Catalyst Center) use this token model, where you hit a token-issuing endpoint first, then call the actual API.

Suppose you are writing a script to "get the list of users" from a SaaS API and run this curl, but it returns 401 Unauthorized: curl -X GET 'https://api.example.com/v1/users' -H 'Authorization: Basic YWxpY2U6c2VjcmV0'. Jumping to "let me re-issue a token" is premature; the correct first step is to re-read which authentication scheme the docs require. The docs say: "Authentication: Bearer token. Obtain a token from POST /v1/auth/token, then send Authorization: Bearer <access_token>." In other words this API does not accept Basic, and you have picked the wrong scheme entirely. The base64 YWxpY2U6c2VjcmV0 merely encodes alice:secret—it is neither encryption nor a valid token. The correct flow is: (1) POST /v1/auth/token with your credentials to obtain an access token, then (2) call the endpoint with -H 'Authorization: Bearer <access_token>'. If the scheme is right (you are sending Bearer) yet you still get 401, the next suspect is an expired token—refresh and resend. But if authentication succeeds and you instead get 403 Forbidden, that is different: "we know who you are, but you lack permission"—a matter of the token's scope/role. The lesson is that even from a single 401, isolating in the order docs requirement (scheme) -> what you sent (scheme/expiry) -> scope reaches the cause by the shortest path without blind retries. Authentication is not "attach anything and it works"—it is matching the exact scheme, location, and name the docs prescribe, to the letter.

2.1.3Section summary

• Assemble a request from method (the goal) + endpoint + headers + (if needed) query/JSON body, and add Content-Type: application/json to a JSON body
• Authentication is Basic (base64, HTTPS required) / API key (docs' exact location and name) / Bearer token (Authorization: Bearer, has expiry); match the docs to the letter
• Isolate a 401 in the order "scheme mismatch -> expiry -> (if 403) insufficient scope," rather than jumping to blind re-issuance