API Testing: A Complete Guide

An API test sends a request and checks the answer. That description of API testing is short enough to hide almost everything that makes the practice worth doing. The interesting question is never whether the request went through, because that part rarely surprises anyone. It is what you are willing to promise about the answer, and how you find out when that promise quietly stops being true.

This guide covers the methods, the strategy that ties them together, and how to run each one. Every chapter is written to stand on its own, so you can read the one you need and follow the links out from there.

API testing is not UI testing without a browser

The difference is not only speed, although a suite that finishes in under a second per case changes how often people bother to run it. The bigger difference is what the test can actually see when something goes wrong.

A UI test observes rendered output, so when it fails you know a page broke and you start bisecting to find out where. An API test observes the interface itself, which means a failure names the endpoint, the status code, the field and the value that was wrong. There is no rendering layer to blame, and no timing flake from an animation that had not finished when the assertion ran.

That precision comes with a cost, and it is better stated early. An API test only checks what you asked it to check, whereas a person looking at a screen notices things nobody thought to assert. Every method in this guide is a different answer to the question of how to ask for more without making the suite fragile.

The specification is the oracle

Every test needs an oracle, meaning the thing that decides whether an answer is correct. Most functional tests carry their oracle inline, because the expected status code and the expected field value are written straight into the test. That works well enough, and it also means the test knows only what its author knew on the day they wrote it.

A specification moves the oracle outside the test. When a case is linked to a documented endpoint, the response is validated against the schema that endpoint promises, so a field that changed type fails the test without anyone editing the test. The specification becomes the thing you maintain, and the tests follow it.

This is the single highest-leverage decision in an API testing strategy, and it is why contract testing gets a whole chapter to itself. Everything else in this guide gets sharper once an oracle outside the test exists.

The map of methods

Seven methods cover the ground between a single request and a live production API, and each one finds a class of defect that the others cannot see.

Method	What it proves	What it cannot see
Functional	One request returns the expected status, headers and values	Whether the shape still matches what you documented
Contract	The response still matches the specification	Whether the values are correct for this business case
Workflow	A multi-step flow holds together and passes state correctly	Anything a single call already covers
Data-driven	The same logic behaves across many inputs and edge values	Interactions between separate calls
Performance	Latency and error rate hold up under concurrency	Correctness, because a fast wrong answer still passes
Security	Authorization and input handling resist abuse	Business logic flaws a scanner cannot recognise
Production monitoring	The deployed service still behaves after the release	Anything before the change reaches production

Two chapters sit alongside the methods, not inside them. Test data is what makes every method deterministic. Environments, auth and secrets is what lets one suite run against all of them.

Effective testing is mostly about three decisions

What you assert, and what you deliberately do not

The most common way to end up with a suite nobody trusts is to assert too much. A full body comparison fails whenever anything changes, including the things you did not care about. People then start ignoring red runs. The opposite failure is asserting only the status code, which passes happily while the payload turns to nonsense.

The useful middle is to assert the contract plus the handful of values this particular test exists to prove. Schema validation covers the shape of the response, while two or three targeted field assertions cover the behaviour. The chapter on functional tests works through the specifics of each assertion type.

Where each test runs

Tests are cheap in some places and expensive in others. A strategy is largely a routing decision.

Stage	What runs there	Why
Local, while developing	A handful of cases against a mock or a dev environment	Feedback in seconds, no shared state to corrupt
Every pull request	Functional plus contract tests against a preview or staging environment	A regression caught here costs a rebase instead of a rollback
Nightly or weekly	The full suite, load tests and the complete security profile	These need time, and nobody should wait for them in review
Production, continuously	Read-only synthetic checks and contract validation	The only place that tells you the truth about the live service

The pull-request row is where the gate belongs, which automating API tests in CI/CD covers in detail.

How tests stay deterministic

A flaky test is worse than no test, because it trains the team to press rerun and stop investigating. Three causes account for most of it. All three have the same shape, which is shared mutable state.

Tests that depend on data another test created will fail when the order changes. Tests that depend on data a human created will fail when someone cleans up the environment. Tests that assert on timestamps, generated identifiers or ordering that the API never promised will fail at random. The fix is to own your data per run, which test data explains through fixtures, seeds and snapshots.

Drift is a permanent condition, not an incident

Between two deploys the specification still promises one thing and the running service has quietly started returning another. Nothing is down, every uptime check is green, and the mismatch surfaces when a consumer breaks.

That is something to plan for, not to react to. Contract tests catch it in the pipeline, and production monitors catch it afterwards by validating live responses against the contract the environment is supposed to be serving. Together they turn a category of silent breakage into something with a first-seen date and an owner.

In Routebase

Routebase gives every one of these methods a home in one workspace, so a test case written for a pull request is the same object a scheduled run and a contract check use later.

Test suites hold cases with declarative assertions, so there are no test scripts to maintain for the ordinary work. Cases chain into scenarios that pass extracted values downstream, and a suite runs once per row of a data set when you need many inputs. The same suite switches from functional to performance mode when you want a load profile instead of a single pass. Security scanning runs the OWASP API Security Top 10 from 2023 against the same environment, and monitors keep validating the live service against the published contract after the release. The CLI and the GitHub Action run any of it in a pipeline and exit non-zero when something fails.

Start with the Test Suites guide in the product documentation, or read on for the method you need. If you want to see the whole thing running, the API testing feature page has the short version.