Walkthrough: Building a REST API Request from the Docs

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)

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

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.

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.