Best practices for testing REST APIs

Testing a REST API means checking more than "does it return 200". A good test suite confirms that the API returns the right status codes, data shapes and errors, handles bad input gracefully, and enforces authentication. This guide covers what to test, how to structure requests, and a workflow that scales from a quick manual check to automated tests in CI.

What to test

1. Status codes. 201 Created for a successful POST, 404 for a missing resource, 401 when unauthenticated, 422 or 400 for invalid input. A wrong status code breaks clients and monitoring even when the body looks right.
2. Response shape. Required fields are present, types are correct, and no internal fields leak out. Validating responses against a schema catches this automatically; see JSON Schema basics.
3. Business rules. Totals add up, state transitions are allowed (you can't ship a cancelled order), and permissions are enforced.
4. Error responses. Every failure returns the same error shape with a useful message; see API error payloads.
5. Edge cases. Empty lists, very long strings, Unicode, missing optional fields, null values, and pagination boundaries.
6. Security basics. Endpoints reject requests without a token, users can't access other users' data by changing an ID in the URL, and rate limits respond with 429.

Structure your requests

Use environments instead of hard-coding

Don't hard-code base URLs and tokens into every request. Use variables, such as {{base_url}}/api/users, and keep a separate set of values for local, staging and production. Most API tools support environments, and test frameworks read them from configuration or environment variables. This also keeps secrets out of version control.

Make tests independent

Each test should create the data it needs and not depend on another test running first. Tests that share state fail in confusing ways when they run in a different order or in parallel.

Prefer specific assertions

javascript
expect(res.status).toBe(201);
expect(res.body.id).toMatch(/^[0-9a-f-]{36}$/);
expect(res.body.email).toBe('user1@example.com');
expect(res.body).not.toHaveProperty('passwordHash');

Assert on the fields that matter rather than comparing the whole response to a saved copy. Snapshot comparisons break every time a harmless field is added.

Handle authentication

• API keys usually go in a header such as X-API-Key. Avoid query parameters, which end up in logs.
• Bearer tokens (often JWTs) go in Authorization: Bearer <token>. Fetch the token once per test run, not per request. To check a JWT's claims, decode it; see JWTs explained.
• Test the negative cases: a missing token, an expired token, and a valid token for a user who lacks permission.

A practical workflow

1. Explore manually. Send requests with curl or an API client and read the responses in the JSON Formatter to understand the shape.
2. Write down the contract. Capture the request and response shapes as an OpenAPI document or JSON Schema.
3. Automate. Write tests with a framework you already use, such as Jest or Vitest with fetch or Supertest, pytest with requests, or REST Assured. Run them in CI on every pull request.
4. Test against a realistic environment. Use a staging environment with production-like data shapes, but never real customer data.
5. Monitor production. Run a few read-only checks on a schedule, so you find outages before your users do.

Debugging failing requests

• Read the whole response: the status, headers and body. Error details are often in headers such as WWW-Authenticate or in a JSON body you didn't print.
• Compare with a working request. Paste both responses side by side; see How to compare two JSON files.
• Check the request body is valid JSON and that Content-Type: application/json is set. A surprising number of 400 errors come from a missing header or a trailing comma; see Validate JSON.
• In the browser, check for CORS. If a request works in curl but fails in the browser, see CORS errors explained.