SpunkArt
Websites, APIs and search

How to test an API by hand with curl and DevTools

You do not need a special app to test a web API. The curl command and your browser’s developer tools show you exactly what goes out and what comes back.

What you are checking

Every API call is a request and a response. When something breaks, the cause is almost always visible in one of five places: the method, the URL, the request headers, the request body, or the response status. Testing by hand means looking at each of them on purpose rather than guessing.

Your first request

curl -i api.example.com/v1/status

The -i flag prints the response headers above the body. The first line shows the protocol and the status code, for example HTTP/2 200. If you want only the headers, use -I, which sends a HEAD request instead. Add -v when you also need to see the request curl sent and the TLS handshake.

Sending JSON

curl -i -X POST api.example.com/v1/notes \
  -H "Content-Type: application/json" \
  -d '{"title": "Test note", "pinned": false}'

Three details trip people up here. The Content-Type header must say JSON or many servers ignore the body. The body must be valid JSON with double quotes. And on Windows Command Prompt the single quotes do not work, so put the JSON in a file and use -d @note.json.

Passing a token without leaking it

Most APIs want an Authorization: Bearer ... header. Do not paste the token into the command where it lands in your shell history. Store it in an environment variable for the session and refer to it:

curl -i api.example.com/v1/me -H "Authorization: Bearer $API_TOKEN"

Reading the status code

CodeMeaningUsual next step
200, 201, 204Success (204 has no body)Check the body matches what you expect
301, 302, 308RedirectAdd -L to follow, or fix the URL
400, 422The server rejected your inputRead the error body; it usually names the field
401, 403Missing or insufficient credentialsCheck the token, its scope and its expiry
404No such route or resourceCheck the path, version prefix and trailing slash
429Rate limitedWait; look for a Retry-After header
5xxThe server failedRetry later and report it with the request details

Testing from the browser

When the call comes from a web page, open DevTools (F12), choose the Network tab, tick Preserve log, then repeat the action. Click the request to see headers, payload and response. Right-click it and choose Copy as cURL to replay the exact request in a terminal, where you can change one thing at a time. A failure that appears only in the browser and not in curl often points to CORS or cookies.

Mistakes to avoid

  • Testing against production with write requests. Use a staging service or a mock.
  • Pretty-printing the response and missing that the status was 500. Always look at the code first.
  • Sharing a copied cURL command in a chat without removing the cookie and authorization headers.

Questions

Why does curl work but my app fails?

Compare the two requests header by header. Common differences are a missing content type, a different base path, or a browser-only rule such as CORS.

Why is there no live tester on this page?

A browser page can only reach other servers that allow it, and sending your tokens through a third-party site is a bad habit. Running the request yourself is safer and shows more.