Every API team has a version of this story: the pipeline is green, the release ships on time, and an hour later someone reports that pagination has been returning the same page of results since Tuesday. The tests passed because nobody ever asked for page two. Most API testing problems are not exotic. They are small blind spots that repeat across projects and languages, and they are usually cheap to fix once you name them.
1. Testing Only the Happy Path
A request with valid inputs returns 200. Ship it. The trouble is that real traffic rarely looks like your fixture data. Clients send empty strings where you expect a name, retry a payment three times because the first response was slow, and pass an identifier that was deleted last week.
For each endpoint, list the inputs it accepts and mark which ones your suite actually exercises. The usual gaps:
- Empty and single-item collections — does the second page of a one-item list return an empty array, or a 404?
- Boundary values: the maximum page size your API allows, zero, and negative numbers
- Optional fields omitted entirely versus present but null
- Non-Latin characters, long strings, and trailing whitespace in identifiers
- Repeated submissions of the same request body
You do not need to cover every case on every endpoint. You do need to know which ones you skipped, and why.
2. Hardcoding IDs, Tokens, and Seed Data
A test that assumes user 42 exists and owns exactly three orders will fail the moment someone reseeds the database or runs the suite against staging. Worse, it will pass for months while silently testing nothing, because the assertions still match whatever data happens to be there.
Generate data inside the test. Create the user, capture the ID from the creation response, use it in the next call, and delete it when the test ends. Append a timestamp or UUID fragment to emails and slugs so parallel runs do not collide. Read tokens from environment configuration rather than pasting a long-lived one into the file. If a test needs a specific state — a locked account, an expired trial — build that state explicitly instead of hoping the seed script produced it.
3. Asserting on Entire Response Bodies
Snapshot-style assertions that compare the full JSON payload are convenient and brittle. Add one new field to a response and forty tests turn red, even though nothing a client depends on has changed. The team starts updating snapshots without reading them, and the suite loses its value.
Split your assertions into two kinds. Use schema validation to confirm structure: required fields present, types correct, no unexpected nulls. Use targeted assertions to confirm behaviour: this order has status shipped, this total equals the sum of its line items. When a field is genuinely part of your contract, assert on it by name. Everything else should be allowed to evolve without breaking the build.
4. Ignoring Status Codes, Headers, and Error Contracts
Many suites check that the response body contains the word "error" and call it done. Clients cannot build reliable retry logic on that. The difference between 400, 401, 403, 404, 409, and 422 determines whether a client should fix the request, refresh a token, stop trying, or wait and retry.
Test the error contract directly. Assert the status code, the error shape your documentation promises (a code, a human-readable message, and the offending field where relevant), and the Content-Type. Check that internal details such as stack traces or database names never leak into a response. Headers deserve the same attention: caching directives, rate-limit counters, and pagination links are part of your API's behaviour, not decoration.
5. Letting Tests Depend on Each Other
Test A creates a cart. Test B adds an item to "the" cart. Test C checks out. It works on one machine, in one order, and falls apart the first time the runner parallelises the suite or someone runs a single test in isolation.
Treat every test as if it were the only one running. Create what it needs in setup, clean up in teardown, and avoid relying on an empty database or a global counter. Where cleanup is genuinely hard, isolate by tenant or namespace: give each test run its own account, so leftover data cannot influence results. If a test cannot run alone, it is not testing what you think it is.
6. Mocking Until the Test Proves Nothing
Mocks are useful. A suite built entirely from them tells you that your code agrees with your assumptions about a service you never call. The provider adds a required field, changes an enum value, or starts returning a nested object instead of a flat one, and your green build ships a broken integration.
Keep fast mocked tests for logic and branching. Add a smaller integration suite that talks to a real instance of each dependency in a staging environment, and run it on every deploy. Where two teams own the boundary, contract tests — where the consumer's expectations are verified against the provider — catch drift before it reaches production. Regenerate stubs from the provider's schema rather than maintaining them by hand.
7. Skipping Authorization and Abuse Cases
Confirming that a logged-in user can read their own profile is the easy half. The half that matters is confirming that user A cannot read user B's profile by changing the ID in the URL, that an expired token is rejected rather than tolerated, and that a token with the wrong scope cannot perform a privileged action.
Add a short authorization pass to every resource that holds user data: request it as the owner, as another user, as an admin, and with no credentials at all. Then test the unglamorous abuse cases — oversized payloads, unexpected content types, deeply nested JSON, requests that arrive twice within a second. These checks are boring to write and remarkably good at finding real problems.
Putting the Fixes to Work
You do not have to rewrite the suite this week. Start with the endpoint that has caused the most production incidents and apply the list below, then repeat for the next one.
- Note which inputs and failure modes the endpoint currently tests, and which it ignores.
- Replace fixed IDs and tokens with values created inside the test.
- Swap full-body comparisons for schema validation plus a few named assertions.
- Assert status codes, error shapes, and headers explicitly.
- Make each test independent enough to run alone, in any order, in parallel.
- Keep one integration suite pointed at a real environment.
- Add an authorization pass for every resource that stores user data.
A test suite earns trust slowly and loses it in a single release. Aim for tests that fail for exactly one reason, tell you what broke, and stay quiet when nothing did. That is a lower bar than it sounds — and a much higher one than most suites currently clear.
Photo: lawrence_monk / Pixabay
