Test Cases for API Endpoint: REST QA Checklist

An endpoint can return 200 OK and still corrupt the product. A create-order request might accept an invalid currency, emit the same event twice, or expose another tenant's record while its response looks perfectly healthy. Useful API testing therefore follows the complete business transaction, not only the HTTP exchange.

The objective is to prove four things together: the request contract is enforced, the caller is allowed to perform the operation, the intended state change happens exactly as specified, and failures leave the system in a safe condition. Those dimensions turn a short endpoint checklist into release evidence.

Define the Contract and the Business Effect

Begin with the API specification, but do not stop there. Record the supported method, path parameters, query parameters, headers, content types, request schema, response schema, status codes, and error format. Then add the product rule that the API description may not express. For POST /orders, that could include inventory reservation, tax calculation, an audit record, and an order.created event.

Write the expected effect beside every response. A 201 response is incomplete evidence if no order exists, while a 400 is unsafe if half an order was saved before validation failed.

Prepare Data That Exposes Boundaries

Create data deliberately instead of depending on whatever exists in a shared environment. For each resource, keep an owned record, another user's record, another tenant's record, an inactive or deleted record, and a record at a business boundary. Give test records unique identifiers so parallel runs cannot collide.

Separate syntactic validity from business validity. A UUID can have a valid shape but refer to no record. A date can parse correctly but fall outside the allowed booking window. An amount can be numeric yet exceed the account limit. These distinctions produce clearer expected results and prevent a single vague “invalid input” case from hiding different defects.

Control the clock when expiry, settlement, or scheduling matters. Control downstream services when testing retries and timeouts. If those dependencies cannot be controlled, capture their version and state with the result so a failure can be reproduced.

Include supported and retired API versions in the dataset. A request using an old media type, version header, or path should follow the published compatibility policy, while a new client must not receive a response shape cached from an older contract. Verify deprecation and sunset headers where the API promises them.

Cover Every Supported Method

Build success cases around semantics, not around a status-code catalog. A useful baseline looks like this:

Assert response headers that clients depend on, including content type, cache controls, correlation IDs, rate-limit metadata, and location. For a no-content response, confirm the body is actually empty. For asynchronous work, verify the operation resource or job status until it reaches a terminal state rather than treating 202 Accepted as completion.

Attack Payload Validation Systematically

Test one rule at a time, then test risky combinations. Cover missing required fields, explicit null, empty strings, whitespace-only values, wrong JSON types, malformed JSON, unknown fields, duplicate keys if the parser behavior matters, invalid enum values, and strings at minimum, maximum, and just beyond each boundary.

For numeric fields, include zero, negative values, precision beyond the supported scale, very large values, and exponential notation. For dates, include impossible dates, offset timestamps, boundary instants, and start dates after end dates. For arrays, cover empty, maximum length, duplicates, invalid members, and mixed-validity batches.

A predictable validation response is part of the contract:

{
  "error": "validation_failed",
  "correlationId": "req-7f3a",
  "fields": [
    {
      "path": "items[0].quantity",
      "code": "minimum",
      "message": "Quantity must be at least 1"
    }
  ]
}

Assert stable error codes and paths. Avoid coupling automation to prose that may be translated or improved unless exact wording is a contractual requirement.

Prove Authentication and Object Authorization

Exercise no credential, malformed credential, expired credential, revoked credential, and valid credentials with insufficient scope. Distinguish 401 from 403 according to the product's policy, and confirm rejected requests create no business mutation.

Authorization must be tested against specific objects. User A should not read, update, or delete User B's resource by changing an ID. A tenant administrator should not cross the tenant boundary. A read-only role should not gain write access through an alternate method, bulk endpoint, nested resource, or undocumented parameter.

Check that error behavior does not reveal whether a protected record exists. Review response bodies, headers, logs returned to clients, and timing where account or object enumeration is a concern. Sensitive fields should remain absent even for authorized callers who do not need them.

Test Idempotency, Concurrency, and State Transitions

Network retries make duplicate requests normal. Send the same idempotency key with the same payload and verify one business operation occurs. Reuse the key with a different payload and expect the documented conflict. Repeat PUT, PATCH, and DELETE requests to establish their actual behavior.

Race two updates against the same version. If optimistic locking is used, one should succeed and the stale request should fail without overwriting newer data. Race purchases against the last inventory unit, password reset redemptions against one token, or withdrawals against one balance. The final state must preserve the business invariant even when both callers receive responses close together.

Model legal state transitions explicitly. An order may move from pending to paid, but paid to pending might be forbidden. Test every allowed edge, a representative forbidden edge, and a retry of the same transition. Verify state history and emitted events, not only the current status.

Exercise Collections, Filtering, and Caching

For collection endpoints, test an empty result, one item, a full page, and more than one page. Confirm page boundaries have no duplicates or missing records when following cursors. Validate limits below minimum, above maximum, and omitted. Ordering should be deterministic, including the tie-breaker when primary sort values match.

Combine filters that should intersect and filters that should return nothing. Check URL encoding, repeated query parameters, case sensitivity, unsupported sort fields, and filters the caller is not permitted to use. A filter must never weaken tenant or row-level security.

Where caching is supported, verify ETag, conditional requests, and invalidation after mutation. Private responses must not become publicly cacheable. A 304 Not Modified response should contain the correct headers and no representation body.

Force Dependencies to Fail Safely

Simulate database timeouts, unavailable downstream services, malformed dependency responses, slow responses, and partial batch failures. Confirm the endpoint returns the documented error, does not expose stack traces or internal hosts, and preserves a correlation ID for support.

Observe retry behavior. Retries should be bounded and restricted to safe operations. If a downstream call succeeds but the response is lost, the recovery path must avoid duplicating money movement, messages, or records. For asynchronous events, test duplicate delivery, delayed delivery, and a dead-letter path.

After every induced failure, inspect durable state. The strongest assertion is often “no order, no charge, no event” or “one completed order and one event,” not merely “received 503.”

Turn the Matrix Into Maintainable Automation

Keep a thin smoke set for deployment health, a broader contract suite for every change, and focused integration tests for state and failure behavior. Generate combinations selectively. Exhaustive Cartesian products create noise, while pairwise coverage plus explicit high-risk combinations usually gives clearer intent.

Make failures self-explanatory by recording the endpoint, sanitized request, response, correlation ID, test data identifier, and relevant state snapshot. Never print access tokens, personal data, or payment details. Run destructive cases against isolated data and make cleanup safe to repeat.

Before releasing an endpoint, prove one success path, each meaningful validation class, every privilege boundary, the critical state transitions, retry safety, and recovery from its most important dependency failure. If the suite can show both the HTTP result and the resulting business state, it is testing the API as a product interface rather than as a status-code generator.