Endpoints, Resources, and Parameters

A URL names a resource

In REST, a URL identifies a resource — a specific thing the API knows about. /devices/SW1/interfaces doesn't describe an action; it names "SW1's interfaces." The HTTP method (GET, so far) is what says what to do with it.

a resource-oriented URL

GET /devices/SW1/interfaces
   ^devices  ^SW1  ^interfaces
   resource  which one   sub-resource

Every segment of the path narrows down which resource this request is about — the URL structure itself carries meaning, unlike a CLI command's flat argument list.

Quick checkConcept check

In REST, what does a URL like /devices/SW1/interfaces represent?

An action to performA specific resource — SW1's interfaces — with the HTTP method (GET, POST, etc.) saying what to do with itA Python function nameA CLI command translated into a URL

Path parameters: which resource

The SW1 in /devices/SW1/interfaces is a path parameter — part of the URL itself, identifying exactly which device.

path_parameter.py

import requests

for hostname in ["SW1", "SW3"]:
  response = requests.get(f"http://127.0.0.1:8765/devices/{hostname}/interfaces")
  print(hostname, "->", response.status_code, response.json()["hostname"])

An f-string builds a different URL per device — the same 'one pattern, many devices' idea as Jinja2's {% for %} loop and Ansible's loop:, now applied to constructing a URL.

output

SW1 -> 200 SW1
SW3 -> 200 SW3

Real, verified output — the same request pattern, a different device each time, just by changing the path parameter.

Quick checkIdentify the correct code

Given hostname = "SW2", which f-string correctly builds the URL for SW2's interfaces?

f"http://127.0.0.1:8765/devices/interfaces/{hostname}"f"http://127.0.0.1:8765/devices/{hostname}/interfaces"f"http://127.0.0.1:8765/{hostname}/devices/interfaces"f"http://127.0.0.1:8765/devices/hostname/interfaces"

Query parameters: filtering the result

A query parameter narrows down what's returned, without naming a different resource. It's appended after a ?:

query_parameter.py

response = requests.get(
  "http://127.0.0.1:8765/devices/SW1/interfaces",
  params={"status": "up"},
)
print(response.url)
print(response.json())

requests builds the ?status=up query string for you from the params dict — no manual string concatenation needed.

output

http://127.0.0.1:8765/devices/SW1/interfaces?status=up
{'hostname': 'SW1', 'interfaces': [{'name': 'GigabitEthernet1/0/1', 'status': 'up'}]}

Real, verified output — SW1 has two interfaces total, but only the one matching status=up came back. The resource (SW1's interfaces) didn't change; what's returned about it did.

Quick checkPredict output

Using params={"status": "down"} against SW1's interfaces (from Lesson 2's data), how many interfaces come back?

ZeroOne — GigabitEthernet1/0/2, the only interface with status downTwoAll interfaces, since status is ignored

Path parameter vs. query parameter

Path parameter

/devices/SW1/interfacespart of the URL structure
Identifies WHICH resource
Required — the URL doesn't make sense without it

Query parameter

?status=upappended after ?
Filters WHAT's returned about that resource
Usually optional — omit it, get everything

devices.csv addressed one thing; this addresses two

devices.csv rows each named one device. A REST URL like /devices/SW1/interfaces names both a device (path parameter) and a sub-resource of it (interfaces) — with query parameters layered on top to filter further. More structure than a flat CSV row, for a genuinely more structured target.

Quick checkScenario

A request needs to fetch SW3's VLANs, filtered to only those named MGMT. Which two mechanisms does this require together?

Two separate requests, one per filterA path parameter (SW3, to pick the device) and a query parameter (to filter by name) — used together in one requestOnly a query parameter — the device doesn't need to be specifiedOnly a path parameter — filtering isn't possible in REST

Key takeaways

A REST URL names a resource; the HTTP method says what to do with it.
A path parameter (like SW1 in /devices/SW1/interfaces) is part of the URL and identifies which resource — required, and usually built with an f-string.
A query parameter (like ?status=up) filters what's returned about that resource — usually optional, and requests builds it for you from a params dict.
The two are combined routinely, not alternatives — verified directly against this module's own mock API.

What you'll learn

A URL names a resource

Path parameters: which resource

Query parameters: filtering the result

Path parameter vs. query parameter