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
| Code | Meaning | Usual next step |
|---|---|---|
| 200, 201, 204 | Success (204 has no body) | Check the body matches what you expect |
| 301, 302, 308 | Redirect | Add -L to follow, or fix the URL |
| 400, 422 | The server rejected your input | Read the error body; it usually names the field |
| 401, 403 | Missing or insufficient credentials | Check the token, its scope and its expiry |
| 404 | No such route or resource | Check the path, version prefix and trailing slash |
| 429 | Rate limited | Wait; look for a Retry-After header |
| 5xx | The server failed | Retry 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.