The API Test Case Template: 9 Fields, One Worked Example

A backend team lead spends the first fifteen minutes of most sprint reviews arguing about how an API test case should be written. One person wants a Gherkin style scenario. Another writes a paragraph. A third pastes a curl command and calls it done. None of them are wrong exactly, but none of them are reusable by the next person either. This post gives you one API test case template, with every field explained and a worked example filled in, so you can settle the argument this afternoon instead of relitigating it every sprint.

The template fields, explained

Copy this structure for any API test case. Each field earns its place.

• id. A stable identifier so the case can be referenced from a requirement, a bug, or a report.
• endpoint. The full path, including path parameters written as placeholders, like /orders/{orderId}/cancel.
• method. The HTTP verb: GET, POST, PUT, PATCH, or DELETE.
• auth/preconditions. Who is calling it, meaning role and token state, and what must exist before the call, such as an order already placed.
• request. The actual body, headers, and query parameters sent, written out in full rather than described.
• expected status. The exact HTTP status code expected back, such as 200 or 404, not a range.
• expected body. The specific fields and values the response body must contain, or the error message it must return.
• teardown. What gets cleaned up after the case runs, so the next run starts clean.
• requirement link. The ticket, spec, or requirement this case verifies, so a reviewer can check the case actually covers what it claims to.

Nine fields sounds like a lot for one test case. In practice most fields are one line each. A case that fills all nine takes about the same time to write as one that skips half of them and gets challenged in review anyway.

A worked example

Here is the template filled in for cancelling an order on a fictional retail API.

• id: ORD-CANCEL-01
• endpoint: /orders/{orderId}/cancel
• method: POST
• auth/preconditions: Logged in customer token. An order with id 8842 exists with status processing, belonging to this customer.
• request: POST /orders/8842/cancel with an empty body and the customer's bearer token in the Authorization header.
• expected status: 200
• expected body: {"orderId": 8842, "status": "cancelled"}
• teardown: Delete order 8842 or reset its status, so the next run does not collide with a leftover cancelled order.
• requirement link: ORD-114, the ticket specifying that a processing order can be cancelled by its owner.

A second case for the same endpoint can reuse the identical template with different values. Change the precondition to an order that has already shipped. Expect a 409 this time, with a body explaining that shipped orders cannot be cancelled. Same fields, different values, and a reviewer compares the two in seconds because the shape never changes.

Reusing setup and steps without copy paste drift

The order cancellation example above is really three related cases. Cancel a processing order. Try to cancel a shipped order. Try to cancel an order that does not exist. Copying the whole template three times by hand is how a team ends up with three slightly different definitions of the same precondition, because someone tweaks the wording in one copy and forgets the other two.

The fix is to separate the parts of the template that repeat from the parts that change. The endpoint, method, and the base auth/preconditions for "a logged in customer with an existing order" are shared across all three cancellation cases. Write that shared setup once, in a place your team already keeps reusable fixtures or a shared preconditions note, and reference it by name from each case instead of retyping it.

What should stay unique per case is the specific precondition variation, the request details that differ, and the expected status and body. That keeps the template light to fill in and means a change to the shared setup, like the login flow changing, only needs to be updated in one place.

When the template feels like overkill

For a one off exploratory check during development, this template is too much ceremony, and that is fine. Reserve it for cases entering your suite, meaning cases that will run repeatedly and that someone else will need to read later. A case checking a quick assumption while debugging does not need a requirement link.

The test is simple: if this case will still exist in three months and someone other than you will read it, fill in all nine fields. If you will delete it by end of day, skip the template entirely.