What is API Testing? How to Test a REST API

Step 1 — read the contract. It documents nine outcomes: 201, 400, 401, 403 FORBIDDEN, 403 INSUFFICIENT_SCOPE, 404, 409, 415 and 422, so the set needs at least nine tests before any boundary. The rules with edges are qty (from 1 to the returnable quantity: 2 for A-100 and 1 for B-200 in O-5001), comment (500 characters), items (at least one entry, each SKU once, only SKUs of the order) and the 14-day window. The test data has no order on the edge of the window, so ask for two more synthetic orders of CUS-101, for example O-5004 delivered on 17 Sep 2026 (14 days before today) and O-5005 delivered on 16 Sep 2026 (15 days), each with A-100 × 1, so that the developer’s request fits them unchanged. Run every test on restored data: each successful return lowers the returnable quantity for the next test. The model set below numbers the tests RT-01 to RT-25; your numbering and wording may differ.

Step 2 — happy path. RT-01 The developer’s request (A-100 × 1, DAMAGED): 201; Location is /api/v1/returns/ followed by the id of the body; Content-Type: application/json and Cache-Control: no-store; the body has every field of a return with the right type — refundAmount a number, not a string, comment null, createdAt in ISO 8601 with an offset — and the right values: orderId O-5001, status requested, items and reason as sent, refundAmount 49.95; response time under 800 ms. Save this response as your baseline. RT-02 Everything in the order: A-100 × 2 and B-200 × 1, reason WRONG_ITEM, with a short comment: 201, both items listed, the comment returned as sent, and refundAmount 219.90 (2 × 49.95 + 120.00), a value that checking the status code alone would never catch.

Step 3 — break the input; each test is RT-01 with one change. RT-03 Body cut off after {"items": [ → 400 MALFORMED_JSON. RT-04 The valid body sent with Content-Type: text/plain → 415 UNSUPPORTED_MEDIA_TYPE. RT-05 items left out → 422 VALIDATION_ERROR, field items. RT-06 "items": [] → 422, field items. RT-07 The boundaries of qty for A-100, whose returnable quantity is 2 (2-value boundary value analysis: each boundary value and its closest neighbour in the adjacent partition): 0 → 422 with field items[0].qty; 1 → 201 (RT-01); 2 → 201; 3 → 422. RT-08 Invalid values and types of qty: -1, 1.5 and "1" (a string) → 422 each. RT-09 SKU C-300, which belongs to another order → 422, field items[0].sku. RT-10 A-100 twice in items → 422. RT-11 reason left out, and reason OTHER → 422, field reason. RT-12 A comment of exactly 500 characters → 201, the comment returned in full; 501 characters → 422, field comment.

RT-13 Order O-9999 → 404 ORDER_NOT_FOUND. RT-14 O-5002, which is only shipped → 409 ORDER_NOT_RETURNABLE, the response the contract gives for an order that is not delivered (see Q4). RT-15 The window: O-5004 (day 14) → 201 if day 14 counts (Q1); O-5005 (day 15) and O-5003 (day 21) → 409. RT-16 A comment with quotes and angle brackets, such as O'Brien "test" <b>x</b> → 201, and the comment comes back exactly as sent, with no 500 and no SQL or stack trace in any message. Send such inputs only to systems you are authorised to test — here, your team’s staging.

Step 4 — authentication. RT-17 No Authorization header → 401 UNAUTHENTICATED and no return data; RFC 9110 also requires every 401 response to carry a WWW-Authenticate header. RT-18 TOKEN_A_EXPIRED → 401 UNAUTHENTICATED. RT-19 TOKEN_B of customer CUS-202 on O-5001 → 403 FORBIDDEN, with nothing about O-5001 in the body; afterwards GET /api/v1/orders/O-5001/returns with TOKEN_A shows no new return, and the same GET with TOKEN_B → 403. RFC 9110 lets a server answer 404 instead, to hide that the order exists; this contract chose 403, so 403 is the expected result. RT-20 TOKEN_A_READ, which only has orders:read → 403 INSUFFICIENT_SCOPE.

Step 5 — state changes and headers. RT-21 After RT-01, GET /api/v1/orders/O-5001/returns → 200 with exactly one return whose id, items, reason and refundAmount match the 201 body. RT-22 The returnable quantity goes down: after RT-01, A-100 with qty 2 → 422 (only 1 is left), qty 1 → 201, then qty 1 again → 422. RT-23 RT-01 plus "status": "approved", "refundAmount": 999 → 201 with status requested and refundAmount 49.95: a client must not be able to set its own refund (the OWASP API Security Top 10 2023 covers this under API3, Broken Object Property Level Authorization). RT-24 Rejected requests change nothing: after RT-07 with qty 3, RT-11 and RT-14, the list of returns of that order is unchanged. RT-25 The RT-02 request sent twice at the same moment → one 201 and one 422; two 201 responses would refund the same items twice. On every response, errors included, assert Content-Type: application/json, Cache-Control: no-store (the data is private), the contract’s error shape, and Location on 201 only.

The last two steps of the method apply as well: record the response time of every test and flag anything above 800 ms even when the response is correct, and compare the times between builds: a time that keeps rising is a regression even while it stays under 800 ms. Then turn the set into a collection that restores the test data, runs on every build and compares RT-01 with the saved baseline. That is 25 tests for one endpoint. The guide’s FAQ names the minimum — one happy path, one test for each documented error, an authentication failure and the boundary values of each parameter — and RT-21 to RT-25 are what a set built only from single responses misses.

Step 6 — the first run. R1 fails on three counts, all named in the guide: 500 for bad input instead of 422 and an error shape that differs from the contract (a string instead of the error object with code, message and field) are two of its common failures, and the message leaks internals (an exception name, a source file and a line number), which the guide’s list of what to assert in every response rules out. Expected: 422 VALIDATION_ERROR with field items[0].qty.

R2 fails and is the most serious: a missing authorization check — the token is valid but belongs to a customer who has no right to this order. Any signed-in customer could request returns, and so refunds, on someone else’s order, and the response shows that order’s data. The OWASP API Security Top 10 2023 lists this as API1, Broken Object Level Authorization. Expected: 403 FORBIDDEN, and no return created. Report it first, with severity Critical, the exact request with TOKEN_B, the 201 response and the return R-9002 it created; after the fix, run RT-19 again as a confirmation test, the GET with TOKEN_B included. R3 fails: 200 OK with an error inside the body, so a client that trusts the status code tells the customer the return was accepted, and the body has yet another error shape. Expected: 422 VALIDATION_ERROR with field reason, and no return created.

Questions for the product owner and the developer. Q1 Does "within 14 days of delivery" include day 14, and is it counted in calendar days in the store’s time zone or in 24-hour periods from the time of delivery? Q2 How are the 500 characters of comment counted for Arabic text and emoji, and is an empty comment accepted? Q3 Is reason case-sensitive, that is, is damaged rejected? Q4 When a request breaks two rules, which error comes first? Examples: another customer’s order with an invalid body, or O-5002, which is not delivered, so none of its quantity is returnable yet (409 or 422?). The usual expectation is the authorization check, so that validation messages reveal nothing about someone else’s order.

Check your own work: every documented status code should appear in your set at least once; each negative test should change exactly one thing in RT-01; and each expected result should name the status code and the error code, not just "an error". In ISTQB terms, the contract is the test basis, each documented response and each rule is a test condition, and RT-07, RT-12 and RT-15 apply 2-value boundary value analysis. If your set had no checks after the response, RT-21 to RT-25, add them: a response can look right while the data behind it is wrong.