Skip to main content
PacketMentor logo
← All topics
Automation & Programmability Foundational

Walkthrough: Building a REST API Request from the Docs

The exact process network engineers follow to turn API docs into a working REST call. Read the method, URL, auth, query params, body. Try it with curl. Fix 4xx. Ship a working script.

Quick summary
  • Every API doc page tells you the same five things: method, URL, auth, params, body. Find them. Nothing else matters for the first call.
  • First call is always a plain curl. Get a 200 before you add anything (auth, pagination, retries) to a Python script.
  • If you get a 4xx, the body usually explains what you got wrong. Read it.

Studying for an exam? Get a free study plan from a Cisco NetAcad instructor. 20 minutes, no card.

Mental model

Cisco objective 2.1 says “Construct a REST API request to accomplish a task given API documentation”. In practice that is a five-step repeatable routine:

  1. Find the five facts on the doc page: method, URL, auth, params, body.
  2. Try with curl first. Get a 200 before you write any code.
  3. Make the request fit together: URL template filled in, query string if any, headers for auth and content-type, body if method is POST/PUT/PATCH.
  4. Read the error if you get a 4xx. The body usually explains.
  5. Only now wrap in Python. The script is 10 lines once curl works.

This topic walks the routine on a realistic example. HTTP essentials covers the HTTP concepts; this one is the API-reading muscle.

The five facts (always on the doc page)

Fact Where to look Example
Method Big colored label at the top GET, POST
URL template Right next to the method GET /devices/{deviceId}/clients
Auth A dedicated “Authentication” section Authorization: Bearer <token>
Parameters Table under “Query parameters” or “Path parameters” ?limit=10&offset=20
Body Under “Request body” with a JSON schema {"name": "sw3", "ip": "10.0.0.3"}

If any of those is missing from the page, scan the top-of-page examples. Vendor API docs vary; the facts are there, just styled differently.

Example walkthrough (Meraki-style, generic)

Docs say:

POST /organizations/{orgId}/networks — Create a new network in an organization. Auth: X-Cisco-Meraki-API-Key: <your-key> Path parameters: orgId (required, string). Body (JSON):

{
  "name": "lab-01",
  "productTypes": ["switch"],
  "timeZone": "America/Los_Angeles"
}

Step 1: fill in the URL template

Your org id is 123456. The URL becomes:

https://api.meraki.com/api/v1/organizations/123456/networks

Step 2: try with curl

curl -X POST \
  -H "X-Cisco-Meraki-API-Key: your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"name":"lab-01","productTypes":["switch"],"timeZone":"America/Los_Angeles"}' \
  https://api.meraki.com/api/v1/organizations/123456/networks

Hit Enter. One of three things happens.

Step 3: handle the response

Status What to do
201 Created Done. Save the response body — it has the new network’s id.
400 Bad Request Read the body. Usually one field is wrong. Fix and resend.
401 Unauthorized API key wrong or missing. Check -H spelling.
403 Forbidden Key is valid but has no permission for this org. Ask your Meraki admin.
404 Not Found The orgId is wrong. Confirm with GET /organizations.
429 Too Many Requests Rate limited. Wait the number of seconds in Retry-After and try again.
5xx Server problem. Wait, retry. If it persists, open a support ticket.

Step 4: translate curl to Python requests

Once curl works, the Python version is mechanical:

import requests

url = "https://api.meraki.com/api/v1/organizations/123456/networks"
headers = {
    "X-Cisco-Meraki-API-Key": "your-key-here",
    "Content-Type": "application/json",
}
payload = {
    "name": "lab-01",
    "productTypes": ["switch"],
    "timeZone": "America/Los_Angeles",
}

r = requests.post(url, headers=headers, json=payload)
r.raise_for_status()                 # raises on 4xx/5xx
print(r.json()["id"])

See the Python requests topic for a deeper look.

Common doc-reading traps

  • URL path vs query parameters. Path params go INSIDE the URL (/devices/{id}); query params go AFTER a ? (?limit=10). Doc tables usually label them separately.
  • Required vs optional. Optional parameters have a default and can be omitted. Required ones must be in the request or you get a 400.
  • Header casing. HTTP headers are case-insensitive, but some servers trip on authorization vs Authorization. Match the docs’ casing when in doubt.
  • Content-Type matters. A JSON body without Content-Type: application/json is often rejected. Set it.
Hands-on lab · 7 minute walkthrough

Read docs, build a request, land the 201

12 steps: list devices with GET, read a client list, build a POST that creates a network. Watch 401 → 403 → 404 → 400 → 201 as you fix the request piece by piece.

Open the lab →
rest-walkthrough · lab
you@laptop:~$ curl -X POST ... /networks
HTTP/1.1 401 Unauthorized
↑ add X-Cisco-Meraki-API-Key header
you@laptop:~$

FAQ

What if the docs do not show an example? Good APIs always do. If you cannot find one, hit the search bar for “quickstart” or “getting started”. Still nothing? File a doc bug and send the vendor the first thing that works.

Should I write a Python script before I curl? No. Debugging Python auth problems is far slower than debugging curl auth problems. Get the HTTP call right first, then transliterate.

Do I need Postman / Insomnia? Nice to have, not required. curl + Python requests cover everything the exam asks for and anything you will do day one on the job.

Master this on a real network

Want this drilled into reflex?

1:1 weekly sessions, live feedback on your labs, and US interview prep: built around the CCNA Automation® exam blueprint. Free first session. No card on file until you decide.

Claim my free session →
Free first session

Stuck on Walkthrough: Building a REST API Request from the Docs?

Walk your plan with a Cisco NetAcad instructor in a free 20 minute call. We find the one thing blocking you and name the next step. No card. No pitch.

  • 20 minutes, 1:1 with a Cisco NetAcad instructor
  • No card, no obligation, no sales pitch
  • You pick the slot that fits your week
Book free session
Free first session

Get your study plan in a free 20-minute call

  • ✓ 1:1 with a senior network engineer, by video
  • ✓ You leave with a written study plan and a realistic exam date
  • ✓ No card, no sign-up, no sales pitch