
In short
- API tests check the layer under the screens, where most business rules actually live. They are faster and more stable than UI tests.
- Check the status code, the response body, the headers, and what changed in the system, not just that you got a 200.
- Most API bugs are found by negative tests: missing fields, wrong types, no permission, and the same request sent twice.
On this page
The checkout page validates the email address. The API behind it doesn’t. For months nobody notices, because everyone uses the page. Then a partner integration starts calling the API directly, and a thousand orders arrive with "N/A" as the email. The bug was always there. It lived in a layer nobody was testing.
APIs are where most business rules really live. Testing them directly is faster than testing through the UI, it is less fragile, and it finds bugs that the screens politely hide.
01The anatomy of an API test
Every API test sends a request and checks a response. A good one checks four things, not one.
- Status code. Did it succeed or fail the way it should?
- Response body. Are the right fields there, with the right types and values?
- Headers. Content type, caching, and anything security-related.
- Side effects. Did the system actually change? Is the order really in the database? Was the email queued? Only once?
test('creating an order returns 201 and stores it', async ({ request }) => {
const res = await request.post('/api/orders', {
data: { email: 'sam@example.com', items: [{ sku: 'LAMP-01', qty: 2 }] },
});
expect(res.status()).toBe(201);
const body = await res.json();
expect(body).toMatchObject({ status: 'placed', total: 42.0 });
expect(typeof body.id).toBe('string');
const saved = await request.get(`/api/orders/${body.id}`); // side effect really happened
expect((await saved.json()).items[0].qty).toBe(2);
});02Status codes that matter
| Code | Meaning | Test that it’s returned when… |
|---|---|---|
| 200 OK | Success, here is the result | You fetch or update something that exists |
| 201 Created | Success, something new was created | You create a resource; check its id comes back |
| 204 No Content | Success, nothing to return | You delete something |
| 400 Bad Request | The request itself is wrong | Fields are missing, malformed or the wrong type |
| 401 Unauthorized | Not logged in | No token, or an expired one |
| 403 Forbidden | Logged in, but not allowed | A normal user tries an admin action, or reads someone else’s order |
| 404 Not Found | It doesn’t exist | You ask for an id that isn’t there |
| 409 Conflict | Clashes with the current state | You cancel an order that already shipped |
| 422 Unprocessable | Well-formed but breaks a rule | Quantity of -3, or a date in the past (some APIs use 400) |
| 429 Too Many Requests | Rate limit reached | You send requests faster than allowed |
| 500 Internal Server Error | The server broke | Should never be the answer to bad input. If it is, that’s a bug. |
03Negative tests find most of the bugs
- Missing required fields, one at a time.
- Wrong types: "two" instead of 2, an array instead of an object, null.
- Out of range values: negative quantities, huge numbers, empty strings, very long strings.
- No auth, expired auth, and the wrong user’s auth. Can user A read user B’s order by changing the id in the URL?
- The same request twice. Does it create two orders or charge twice?
- Unexpected extra fields. Can a user set
"role": "admin"by adding it to their profile update?
04Retries and duplicate requests
Networks drop connections. Mobile apps resend requests when the signal comes back. Payment providers deliver the same webhook twice. A good API handles all of this without creating two orders or charging a card twice, a property called idempotency: doing the same thing twice has the same effect as doing it once.
- Send the same create request twice in quick succession and check only one record exists.
- If the API supports an idempotency key header, send two requests with the same key and check the second returns the first result instead of creating a new one.
- Replay the same webhook payload twice and check the order moves state only once.
- Time out a request on the client side, then retry it, and check the server didn’t complete it twice.
05Contracts: stop integrations breaking silently
When one team’s service calls another’s API, a change on one side can break the other without either team’s own tests failing. Contract testing fixes that: the consumer writes down exactly what it expects from the API, and the provider checks every change against those expectations before it ships. Pact is a widely used tool for this. Even without a tool, comparing your OpenAPI schema between versions catches removed fields and fields that became optional.
06Tools to start with
| Tool | Good for |
|---|---|
| Postman or Bruno | Exploring an API by hand and saving requests as collections |
| curl | Quick checks from the terminal, and reproducing bugs in a bug report |
| Playwright, REST Assured, pytest + requests | Automated API tests in code, run in CI |
| Pact | Consumer-driven contract tests between services |
API test checklist
- Every endpoint checks status, body, headers and side effects
- Each required field has a test where it is missing
- Wrong types and out-of-range values return 4xx, never 500
- Requests without auth, with expired auth and as the wrong user are refused
- Repeating a create request doesn’t create duplicates
- Unexpected fields can’t change protected properties
- Schema changes are compared between versions
Frequently asked questions
What is API testing?
Testing an application’s programming interface directly, by sending requests and checking responses and side effects, without going through the user interface.
What should I check in an API response?
The status code, the response body’s fields, types and values, important headers, and whether the system actually changed as expected.
What is the difference between 401 and 403?
401 means the request isn’t authenticated: no valid login or token. 403 means the caller is authenticated but not allowed to do this particular thing.
Is API testing better than UI testing?
It is faster and more stable, and it tests business rules more directly. UI tests are still needed for what users actually see and do. Most teams want many API tests and fewer UI tests.
What is contract testing?
A way to check that an API still provides what its consumers depend on. Consumers record their expectations, and the provider verifies each change against them before release.
Written by
Vihari Panyam
QualityAIQ