REST API testing checklist: practical checks, examples and interview answers
“Send every method and check the status code” is not an API test strategy. A useful check connects the contract, input partitions, permissions, persisted state and downstream effects. This guide shows how to build that model for a real order endpoint and how to explain it at a QA interview.
- Model the resource and rule
- Prepare actors and data
- Send positive and negative requests
- Verify response, state and side effects
| Layer | Question | Evidence |
|---|---|---|
| Transport | Did HTTP behave as promised? | Status, headers, content type, timing |
| Contract | Is the response structurally valid? | Required fields, types, formats, error schema |
| Business | Are values and transitions correct? | Totals, ownership, limits, allowed status change |
| State | What was actually persisted? | Follow-up GET, database or emitted event |
| Integration | What happened outside this service? | Payment, queue, email, retry and reconciliation evidence |
1. Turn documentation into a test model
Start with the resource, not the tool. For POST /orders, define who may call it, required headers, request fields, field constraints, successful response, error format and the order state after creation. Mark unclear rules as questions rather than copying current behavior into the expected result.
Build a compact decision table: authenticated or not, cart empty or not, stock sufficient or not, payment required or not. It exposes combinations that a flat list of endpoints misses. Record environment and API version because a correct response from the wrong build is not useful evidence.
- Name the business invariant protected by the endpoint.
- Separate documented rules from assumptions.
- Record version, environment and test-data owner.
- Map each response to the state transition it promises.
Practice task
Draft a decision table for POST /orders using authentication, empty cart and stock availability. Count the meaningful combinations.
2. Methods, status codes, headers and content negotiation
HTTP semantics are part of the contract. GET is safe; PUT and DELETE are defined as idempotent; POST is not automatically idempotent. Check what repetition means for this product instead of memorizing one status per method. A 200 with an error object can still violate the contract.
Verify Content-Type, Location after resource creation when specified, caching headers where relevant and correlation identifiers used for investigation. Send unsupported media types and unacceptable response formats. Distinguish 400 malformed syntax, 401 missing or invalid authentication, 403 insufficient permission, 404 missing resource, 409 state conflict and 422 semantically invalid input according to the actual contract.
POST /orders HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: order-77-cart-19
{"delivery_address_id": 55}
Practice task
For a missing token, expired token and valid token without permission, define expected responses without assuming all failures are 401.
3. Input validation and test design
Apply equivalence partitions and boundaries to every field with a rule. For quantity 1–10, test 0, 1, 10 and 11 plus wrong types, missing, NULL and decimal values. For strings, consider empty, whitespace, length, encoding and normalization. Do not generate dozens of arbitrary values that exercise the same partition.
Check cross-field and state-dependent rules too. A syntactically valid coupon may be expired; a valid address may belong to another user; a valid product id may be out of stock. The error must identify the rejected field or rule without leaking stack traces or internal SQL.
valid: {"quantity": 1}, {"quantity": 10}
invalid: {"quantity": 0}, {"quantity": 11}
type: {"quantity": "2"}, {"quantity": 2.5}
missing: {}, {"quantity": null}
Practice task
Partition an email field into meaningful valid and invalid classes, including case normalization and duplicate registration.
4. Validate schema, values and persisted state
Schema validation checks required fields, types and formats; it does not prove that a total is correct or that the record was saved. Compare business values with an independently calculated oracle. For two eligible items at 690 with a 10% discount, compute the expected total from the agreed rounding rule rather than accepting the returned number.
Follow a write with a read through a supported interface. If POST says 1242 but GET says 1380, persistence or read-model synchronization is suspect. If both say 1242 but the payment provider charged 1380, the defect is downstream. These observations lead to different reports.
pm.test('created', () => pm.response.to.have.status(201));
pm.test('json response', () => pm.expect(pm.response.headers.get('Content-Type')).to.include('application/json'));
const order = pm.response.json();
pm.test('expected total', () => pm.expect(order.total).to.eql(1242));
pm.environment.set('order_id', order.id);
Practice task
Design response and follow-up checks for creating a CRM customer from a lead. Include the repeated-conversion case.
5. Authentication, authorization and object ownership
Authentication answers who the caller is; authorization answers what that caller may do. Test no token, malformed token, expired token, wrong role and access to another user’s object. Hiding a button in the UI does not protect the API.
For object-level authorization, create two synthetic users. User A creates an order; user B tries GET, PATCH and DELETE using A’s id. Also test list, search, export and nested resources because a protected detail endpoint can coexist with a leaking search endpoint. Use only accounts and records you are allowed to test.
Actor A + order A: GET allow, PATCH allow Actor B + order A: GET deny, PATCH deny Admin + order A: follow documented role policy Anonymous : deny without revealing data
Practice task
Build an actor-by-action matrix for a CRM customer owned by one manager and visible to a supervisor.
6. Idempotency, retries, concurrency and pagination
Clients retry after timeouts, proxies repeat calls and users double-click. Re-send the same request with and without the same idempotency key, then check that the business effect matches the contract. Test parallel requests for one coupon, one lead conversion or the last stock item.
For pagination, verify stable ordering, no overlap or gaps, valid metadata and boundaries for page size. Create or remove an item between page requests if the API claims cursor stability. Rate-limit tests must check the exact boundary, headers and reset behavior rather than only provoking one 429.
- Same key and same body.
- Same key and different body.
- Timeout before the client sees the response.
- Two requests started concurrently.
- Limit minus one, limit, and limit plus one.
Practice task
Design a test for two users buying the final item. State the allowed outcomes and the stock invariant.
7. Dependency failures and asynchronous processing
An API may return before a queue consumer, payment provider or email service completes. Separate accepted work from completed work. Define how status is polled, which event proves completion, how long eventual consistency may take and what happens after the timeout.
Simulate dependency timeout, 5xx, malformed response, duplicate event, out-of-order event and unavailable queue. Verify retry policy, dead-letter handling, idempotent consumers and reconciliation. Avoid asserting that a notification was delivered merely because the service published a message.
POST /exports -> 202 + export_id
GET /exports/{id} -> queued | processing | ready | failed
ready -> download URL works and belongs to requester
failed -> reason is safe, retry policy is observable
Practice task
Map the states and evidence for order creation followed by payment and email confirmation. Mark which system owns each transition.
8. Performance, automation and a useful test report
Performance checks need a workload and threshold: concurrent users or requests per second, data volume, warm-up, percentile and error budget. “The API is fast” is not measurable. Track p95 or p99 together with errors and resource saturation, and distinguish a single-request benchmark from load testing.
Automate stable, valuable checks: contract, critical business rules, authorization matrix and regression-prone paths. Keep data isolated, avoid chained tests that hide the first failure and report request id, sanitized request/response, environment, expected state and observed side effects. A collection that only checks 200 is automation of weak evidence.
- Fast contract tests on each change.
- Integration tests for storage and dependencies.
- A small critical-path smoke after deployment.
- Broader regression selected by changed risk.
- Observability checks for latency, errors and queues.
Practice task
Turn five checks from this article into a CI suite. For each, name setup, assertion, cleanup and evidence shown on failure.
REST API testing FAQ
Is Postman enough for API testing?
Postman is a useful client, but the skill is modeling the contract, data, risks and side effects. The same checks can run through another client or an automated test framework.
Should every endpoint have the same checklist?
Use a common baseline for transport, contract, validation and authorization, then add checks from the endpoint’s risk. A payment, search endpoint and asynchronous export require different depth.
Do all API errors need different status codes?
No universal mapping fits every product. The important part is an agreed, consistent contract that lets clients distinguish authentication, permission, validation, missing resources and conflicts without leaking internals.
How do I know that API coverage is sufficient?
Map tests to documented rules, state transitions, actors, input partitions, integrations and risks. Endpoint count or code coverage alone does not show whether important business behavior is protected.
A strong API test follows the effect beyond the first response. It explains which rule was checked, which actor and data were used, what state should exist and which uncertainty remains.