REST API testing is easier to repeat when every request is treated as a small, documented experiment. This workflow shows how to build requests, inspect responses, compare browser tools, curl, API clients, and automated runners, then capture enough detail to reproduce a failure without exposing credentials.
Overview
A useful API test answers more than “did the request work?” It records what was sent, where it was sent, what came back, how long the exchange took, and whether the result matched the contract. Start with the endpoint and HTTP method, then add query parameters, headers, authentication, and a request body only when the endpoint requires them.
Use the simplest tool that fits the task. Browser developer tools are convenient for inspecting requests made by a web application. curl is portable and easy to paste into an issue or terminal. A dedicated API client helps manage collections, environments, and readable response views. An automated test runner is the right choice when the request must protect a regression or run in continuous integration.
| Tool | Best use | Limit to remember |
|---|---|---|
| Browser developer tools | Inspect requests initiated by a frontend and compare browser behavior | Not ideal for repeatable team-wide test suites |
curl | Reproduce a request locally, on a server, or in a bug report | Headers and long JSON bodies can become difficult to read |
| API client | Organize environments, saved requests, and response inspection | Shared collections can accidentally contain secrets |
| Automated test runner | Run contract, integration, and regression checks consistently | Requires setup, stable test data, and deliberate cleanup |
Before testing a JSON endpoint, validate and format the payload so syntax errors do not look like server-side failures. The JSON validation and formatting guide covers malformed JSON, data types, and payload checks. For response headers, caching, and content-type issues, use the HTTP headers reference.
Checklist by scenario
Testing a new endpoint
- Confirm the contract. Write down the URL, method, required parameters, authentication method, accepted content type, expected response type, and documented status codes.
- Start with a minimal valid request. Send only the required fields. Add optional filters or nested data after the basic case succeeds.
- Check the request itself. Verify the HTTP method, URL encoding, query parameter names, header spelling, and whether the body is valid JSON. Set
Content-Type: application/jsonwhen the server expects JSON. - Inspect the response as a set. Record the status code, response headers, body shape, error fields, and approximate duration. A successful status does not by itself prove that the returned data is correct.
- Try deliberate boundary cases. Test a missing required field, an invalid value, an empty result, an unknown identifier, and a request that should be rejected. Confirm that errors are understandable and consistent with the contract.
Reproducing a failing request with curl
Reduce a browser or client request to the smallest command that still fails. Keep the URL, method, non-sensitive headers, query parameters, and representative body. Replace tokens, cookies, personal data, and internal identifiers with placeholders.
curl --request POST \
--url 'https://api.example.test/v1/items?dry_run=true' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <redacted-token>' \
--data '{"name":"sample","enabled":true}'
Use verbose output only in a controlled environment, because it can reveal credentials or sensitive request details. If the failure depends on a browser-only condition, compare the browser’s Network panel with the command rather than copying every header automatically. Headers related to cookies, tracing, or browser state may be unnecessary—or may explain the difference.
Testing authentication and permissions
- Test an unauthenticated request separately from an authenticated request.
- Use a token with the smallest practical scope for testing.
- Check behavior for an expired, malformed, or incorrectly scoped token without recording the token value.
- Distinguish authentication failures from authorization failures in your notes.
- Never commit access tokens, cookies, API keys, or signed request strings to a collection or repository.
Testing pagination, rate limits, and errors
For paginated resources, record the page size, cursor or offset, ordering, and behavior at the end of the collection. Confirm that the next-page mechanism is stable and that changing page size does not silently omit records. For rate-limited endpoints, test the documented response and inspect any retry guidance without creating unnecessary traffic. For error responses, capture the status, machine-readable error code if available, human-readable message, and correlation or request identifier. Do not assume every failure uses the same JSON structure.
Turning a successful request into an automated check
Once a request is understood manually, move the important assertion into a test runner. Assert the status code, content type, required response fields, important data types, and a business rule that matters to the integration. Avoid asserting the entire response when fields such as timestamps, identifiers, or ordering can legitimately change. Use isolated test data and clean it up when the endpoint changes server state.
What to double-check
When a request fails, compare the working and failing versions one dimension at a time:
- Environment: Confirm the host, API version, region, database state, and feature flags. A correct request sent to the wrong environment can produce a misleading result.
- URL and encoding: Check trailing slashes, path identifiers, reserved characters, and repeated query parameters. Encode values according to the endpoint’s expectations rather than concatenating arbitrary user input.
- Headers: Compare
Accept,Content-Type, authorization, conditional-request headers, and any required idempotency or correlation header. Remove irrelevant headers to isolate the cause. - Body: Confirm JSON punctuation, field names, capitalization, null handling, numeric types, and required nesting. Format the body before reviewing it; a readable payload makes differences easier to spot.
- Status and timing: Record whether the response is a client error, server error, redirect, or successful response with an invalid body. Note whether the delay occurs before the response, during transfer, or in client-side processing.
- Reproducibility: Run the same request more than once when safe. If results change, record the time, input data, concurrency, and any server-generated identifiers.
For failures involving certificates, redirects, or mixed content in a browser, consult the TLS and HTTPS troubleshooting guide. A request that works from a terminal but fails in a browser may have a transport or browser-policy difference rather than an API contract problem.
Reusable request-debugging template
Use this structure in an issue, pull request, incident note, or regression test:
- Endpoint and method: redacted host if necessary; include the path and HTTP method.
- Environment: local, test, staging, or production; include relevant version or deployment identifier.
- Authentication: scheme and scope only; never include the credential.
- Parameters and headers: list values that affect behavior and redact sensitive values.
- Payload: provide a minimal representative body with fabricated or approved test data.
- Observed result: status, response body shape, headers of interest, and timing.
- Expected result: the contract or business outcome you expected.
- Reproduction: sanitized
curlcommand, client request, or test name. - Frequency: always, intermittent, or limited to a specific input or environment.
Common mistakes
- Testing only the happy path: A valid response does not verify validation, permissions, empty results, or failure handling.
- Copying secrets into evidence: Exported client collections, verbose logs, screenshots, and terminal history can all retain credentials.
- Changing several variables at once: Alter one part of the request between attempts so the cause remains identifiable.
- Ignoring response headers: Content type, caching, location, retry, and correlation headers can explain behavior that is not visible in the body.
- Assuming status codes tell the whole story: Validate the response schema and business meaning, not only the numeric status.
- Using production data casually: Prefer fixtures and synthetic values, especially for destructive or state-changing tests.
- Automating an unstable example: First understand data dependencies, timing, and cleanup. Otherwise a regression test may create noise instead of confidence.
When to revisit
Return to this checklist whenever a new endpoint is introduced, an API version changes, authentication scopes are revised, or a frontend integration begins sending different data. Revisit it during regression reviews, before a deployment that changes request handling, and after an incident involving status codes, timeouts, pagination, or rate limits.
Also review saved API-client collections and automated tests when tools, environments, or team workflows change. Remove stale requests, refresh example payloads, verify that secrets are still externalized, and confirm that tests assert the current contract rather than an accidental implementation detail. Before closing a bug, preserve a sanitized reproduction and convert the important expected behavior into an automated check where practical.
The practical sequence is simple: build the smallest request, inspect every meaningful part of the response, compare one variable at a time, document the result without credentials, and automate the behavior worth protecting. That process works for a first endpoint test, a production investigation, and the next integration your team needs to maintain.