API testing: the complete guide

What is API testing?

API testing is the practice of sending requests directly to an application's endpoints and asserting on what comes back — the status code, the response body, the headers and the time it took. Because it bypasses the user interface entirely, an API test talks to the same surface your mobile app, your web front end and your partners' integrations talk to.

That distinction is what makes it valuable. A UI test that clicks through a checkout flow might take 30 seconds and break because a button moved four pixels. The API test behind the same flow takes 40 milliseconds and only fails when the behaviour genuinely changed.

Why API testing matters more than it used to

Modern applications are assemblies of services rather than single programs. A single page view can fan out into a dozen internal API calls, and each one is a place where a contract can quietly break. Postman's State of the API research has reported that the large majority of surveyed teams now describe themselves as working API-first — the interface is designed before the implementation, which makes the interface the thing most worth testing.

The economics also favour it. API tests sit in the sweet spot of the test pyramid: broader in scope than unit tests, so they catch integration defects, but far faster and more stable than end-to-end UI tests. A suite of several hundred API tests can run in the time a handful of browser tests take to start up.

The ten types of API testing

"API testing" is an umbrella. These are the disciplines underneath it, roughly in the order most teams adopt them.

Functional testing

The foundation. For each endpoint, confirm the happy path returns the expected status and body, then confirm the failure paths return sensible errors. A well-covered endpoint typically needs one happy path, two to four edge cases, two to three negative cases and one or two security probes — roughly 6 to 10 assertions.

Smoke testing

A shallow, fast pass over the endpoints that would halt the business if broken: authentication, the primary read path, checkout or payment. If a smoke suite takes longer than about five minutes, it has stopped being a smoke test.

Integration and regression testing

Integration tests chain endpoints into a real workflow — register, log in, create, pay, fetch receipt — carrying state between steps. Regression tests re-run a saved baseline and diff the responses, which is how you catch the field that silently changed type three releases ago.

Performance testing

Four distinct shapes, often conflated: load holds expected traffic steady, stress pushes past it to find the breaking point, spike jumps instantly from low to very high, and endurance holds moderate traffic for hours to surface memory leaks. Report p95 and p99 latency rather than averages — see the load testing guide for why averages hide exactly the failures users notice.

Security and fuzz testing

Security testing asserts on what the API must refuse to do. The OWASP API Security Top 10 is the standard reference, and Broken Object Level Authorization — changing an ID in a URL and receiving another user's data — has headed every edition of that list. Fuzz testing attacks the same surface from a different angle, sending malformed and unexpected input to find the validation gaps that produce 500s instead of 400s.

Contract and chaos testing

Contract tests assert on the whole response schema rather than the two fields a given test happens to read, which is why they catch drift that integration tests sail past. Chaos tests inject latency and failure to prove your timeouts, retries and circuit breakers actually work.

How to test an API, step by step

1. Map the surface. Start from an OpenAPI or Swagger document if one exists — it declares every path, method, parameter and response code, which is most of what a test case needs. If there is no spec, discovery can probe conventional paths and infer schemas from live responses.
2. Handle authentication. Most meaningful endpoints sit behind a Bearer token, API key or Basic auth. Use a dedicated least-privilege test account and inject its credentials as a secret rather than committing them.
3. Write the happy path. One valid request per endpoint, asserting status code, response schema and latency.
4. Add the unhappy paths. Missing required fields, wrong types, out-of-range values, absent credentials, valid credentials without permission. This is where most real defects live, and where most hand-written suites are thinnest.
5. Chain the workflows. Extract the token from login, the ID from create, and feed them forward. Hard-coded IDs are the most common source of flaky API tests.
6. Wire it into CI. Functional and contract tests on every pull request, regression on merge, smoke after deploy, and performance on a schedule. See the CI/CD guide for the full staging.

What to assert on

A test that only checks status === 200 will pass while the API returns an empty body, the wrong shape, or someone else's data. Assert on four layers:

• Status code — 200/201 for success, 400 for malformed input, 401 for missing credentials, 403 for insufficient permission, 404 for missing resources, 409 for conflicts, 422 for semantically invalid input. Treat an unexpected 500 as a failure, never a pass.
• Body schema — field names, types, nullability and required properties, validated against the declared schema rather than spot-checked.
• Headers — content type, caching, CORS and the security headers that are cheap to get right and commonly missed.
• Latency — a per-endpoint budget, so a response that becomes ten times slower fails rather than passing silently.

The tooling landscape

Tools cluster into four groups, and most teams end up using one from each:

• Request clients — Postman, Insomnia, Bruno, Hoppscotch. Excellent for exploring an API by hand; the test suite is something you build manually on top. See the alternatives roundup.
• Load testing tools — JMeter, k6, Gatling, Locust. Purpose-built for traffic generation, generally scripted. Compare against JMeter and against k6.
• Code frameworks — REST Assured, pytest with requests, supertest. Maximum control, maximum maintenance.
• Platforms — tools that generate the suite rather than asking you to write it, and cover several disciplines at once.

The trade-off is consistent: the more control a tool gives you, the more of the test-writing labour it leaves with you. That labour, not licensing, is the dominant cost of API testing for most teams.

Common mistakes

• Testing only the happy path. Error branches are where production incidents come from, and they are usually the least covered.
• Asserting on status codes alone. A 200 with the wrong body is still a defect.
• Sharing mutable test data. Tests that depend on a fixed database state fail in random order for reasons unrelated to the code.
• Sleeping instead of polling. Fixed waits make suites slow and flaky at the same time.
• Letting flakes accumulate. Once a suite fails intermittently, people stop reading the results — at which point the suite has negative value. Quarantine flaky tests rather than tolerating them.
• Never testing the limits. If you have never run the API to its knee point, its capacity is a guess.