The API Testing Checklist: 6 Fields for a Real API Test Case

An SDET opens a pull request on Friday afternoon and finds four new API test cases waiting for review. Two of them look fine at a glance. One asserts only that the response came back with status 200, nothing about the body. One has no auth state written down at all, so nobody knows if it ran as an admin or a guest. This happens most weeks on most teams, because writing an API case is easy and writing a case that actually proves something is not. This post is an API testing checklist you can run in under two minutes per case, so weak cases get caught in review instead of six months later.

The API testing checklist itself

Run every API test case past these six checks before it enters the suite. Reject anything that fails more than one.

• One behaviour. If the case description needs "and" to explain what it proves, split it into two cases.
• Request fully specified. Method, path, headers that matter, query params, and body are all written out, not implied.
• Auth state stated. The case says explicitly whether it runs as admin, a regular user, an expired token, or no token at all.
• Exact expected response. Both the status code and the shape of the body are asserted, not just "should succeed."
• Isolation and data set up. The case states what data must exist beforehand and what it creates, so it can run on its own.
• Traceable to a requirement. The case links back to the behaviour or ticket it verifies, not just a folder it happens to sit in.

A case that scores six out of six earns its place in the suite. A case that scores two out of six is decorative. It will turn green on every run regardless of whether the endpoint actually works.

Think about a checkout API with an endpoint that applies a discount code. A decorative case might just call the endpoint and check for a 200. A real case states that it runs as a logged in customer with an empty cart, adds one item priced at 40 dollars, applies the code SAVE10, and expects a 200 with a body total of 36 dollars. The second version fails loudly the day the discount logic breaks. The first version stays green.

Generated versus hand written cases

Teams increasingly generate a first draft of API cases from an OpenAPI spec or from recorded traffic, then hand write the ones that matter most. The two need different scrutiny, because they tend to fail the checklist in different places.

On a generated case, check the expected response first. Generators are good at filling in the request from a schema. They often default to a check that the status code falls in the 2xx range. That is weak. Tighten it to an exact status and a concrete field or two from the body before you trust it. A generated case for a product lookup endpoint might only check for a 200. Add an assertion that the body contains the expected product name and price, and the case suddenly proves something.

On a hand written case, check isolation first. A person writing a case by hand tends to lean on data that should already be there from a previous manual run. That quietly breaks the case the moment someone runs the suite fresh, say on a new CI environment with an empty database. Ask the author what the case creates and what it assumes exists already.

When it belongs at the contract layer instead

Not every check about an API deserves a full request and response test case. Some belong at the contract layer.

A contract check is a schema validation. It says a field is always a string, or always present, regardless of which endpoint or scenario is being exercised. It is not tied to one behaviour.

Push a check down to the contract layer when it is true for every response from that endpoint, not just one scenario. The rule that a user_id field is always an integer belongs at the contract layer. The rule that deleting an order with status "shipped" returns a 409 belongs in a full case. That rule is about one specific behaviour, not the shape of every response.

Keeping that boundary clean saves reviewers from reading the same schema assertion copied into forty separate cases. A team running a 300 case API suite that checks response shape inside every single case will spend real review time on the same three lines, over and over. Move that check to the contract layer once, and a schema change surfaces in one place instead of forty.

Using the checklist in review, not just at write time

The checklist works best as a gate in code review, not a retrospective audit. Paste it into the pull request template for anything touching the API suite. Ask the author to self score before a reviewer looks at it. That single change catches most of the weak cases before a second person's time is spent on them.

For teams with a large existing suite, an audit is still worth doing once. Pick a sample of maybe 30 cases. Score each one against the six checks. You will usually find that the missing field is auth state or isolation, since those are the two easiest to skip when you are moving fast on a Thursday before a release.

One more habit worth building: when a bug reaches production because a case was too vague to catch it, treat that as a prompt to rerun the checklist on the case that should have caught it, not just to add a new one.