Testing APIs with Postman and curl

Why test by hand first

Before you write a Python script against an API, you want to know three things: does the endpoint answer, what does it need, and what does it send back. A manual client lets you change one thing at a time and see the result immediately. Testing by hand also produces something useful for colleagues: a curl command you can paste into a ticket, or a Postman collection the whole team can reuse.

Only test APIs you own or are authorised to use, ideally a lab system or vendor sandbox. Even read-only requests can count as unauthorised access on someone else’s system.

curl essentials

curl is installed on Linux, macOS and current Windows. These options cover most API work:

# read a list of devices and pretty-print with jq
curl -s -H "Authorization: Bearer $NMS_TOKEN" \
     -H "Accept: application/json" \
     "https://nms.example.com/api/v1/devices?site=london" | jq '.[] | {name, ip}'

# create a VLAN from a JSON file and show only the status code
curl -s -o /dev/null -w "%{http_code}\n" -X POST \
     -H "Authorization: Bearer $NMS_TOKEN" \
     -H "Content-Type: application/json" \
     -d @vlan30.json \
     https://nms.example.com/api/v1/vlans

Tip: avoid -k (insecure), which turns off certificate checks. If a lab device uses a private certificate authority, point curl at it with --cacert lab-ca.pem instead.

Postman essentials

Postman is a popular graphical API client; open-source alternatives such as Bruno and Insomnia work in a similar way. Key ideas:

• Collections group related requests, such as Devices, VLANs and Users, in folders.
• Environments hold variables like {{base_url}} and {{token}}, so one collection works against lab and production by switching environment.
• Authorisation tab sets bearer tokens, basic auth or OAuth 2.0 for a whole collection.
• Tests are small JavaScript checks that run after each response, for example that the status is 200 and the reply contains a list.
• Code generation turns a working request into curl or Python, a quick start for scripts.

pm.test("status is 200", () => pm.response.to.have.status(200));
pm.test("returns a list", () => pm.expect(pm.response.json()).to.be.an("array"));

Mark token variables as secret, keep them in the current (local) value rather than the shared value, and check what you sync to any cloud workspace. A collection exported with a live token is a leaked credential.

Troubleshooting checklist

1. No response or timeout: check DNS, routing, firewall rules and the port (curl -v shows where it stops).
2. Certificate error: the client does not trust the server’s certificate. Fix trust; do not disable verification.
3. 401: token missing, expired or sent in the wrong header.
4. 403: authenticated but lacking a role or scope.
5. 400 or 415: body is invalid JSON or Content-Type is missing.
6. Results look short: look for pagination fields such as next or offset.

At work, a short curl command in a change ticket is a clear record of what was tested. In interviews, being able to explain each curl option shows you understand HTTP rather than just clicking buttons.