# API Testing: A Complete Guide — Routebase

> What API testing is, which methods exist, and how they fit together into a strategy that catches breakage before your consumers do.

Canonical page: https://routebase.dev/guides/api-testing/
Guide overview · 12 chapters · Last reviewed 2026-09-12 · The Routebase Team

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](/guides/api-testing/contract-testing-vs-integration-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](/guides/api-testing/functional-api-tests/) | One request returns the expected status, headers and values | Whether the shape still matches what you documented |
| [Contract](/guides/api-testing/contract-testing-vs-integration-testing/) | The response still matches the specification | Whether the values are correct for this business case |
| [Workflow](/guides/api-testing/api-integration-testing/) | A multi-step flow holds together and passes state correctly | Anything a single call already covers |
| [Data-driven](/guides/api-testing/api-test-data/) | The same logic behaves across many inputs and edge values | Interactions between separate calls |
| [Performance](/guides/api-testing/api-performance-testing/) | Latency and error rate hold up under concurrency | Correctness, because a fast wrong answer still passes |
| [Security](/guides/api-testing/api-security-testing/) | Authorization and input handling resist abuse | Business logic flaws a scanner cannot recognise |
| [Production monitoring](/guides/api-testing/api-monitoring-and-contract-drift/) | 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](/guides/api-testing/api-test-data/) is what makes every method deterministic. [Environments, auth and secrets](/guides/api-testing/api-testing-environments/) 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](/guides/api-testing/functional-api-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](/guides/api-testing/automated-api-testing-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](/guides/api-testing/api-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](/guides/api-testing/api-monitoring-and-contract-drift/) 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.

_Screenshot: The test runner holds suites and scenarios on the left, the cases of the open suite in the middle, and the results of a run on the right._

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](https://docs.routebase.dev/test-suites/) 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](/api-testing/) has the short version.

## Frequently asked questions

### What is API testing?

API testing exercises an interface directly over HTTP instead of driving a user interface. A test sends a request and then checks the answer, which covers the status code, the headers, the body, the shape of that body against the contract, and how long the response took. Because there is no browser in the way, the tests run in seconds, they say precisely which endpoint broke, and they can run against every environment from a laptop to a production monitor.

### What are the main types of API testing?

Functional tests check that one request returns the right answer. Contract tests check that the answer still matches the specification. Workflow tests chain several calls into a business flow and pass values between them. Data-driven tests repeat one suite across many input rows. Performance tests measure behaviour under load. Security tests probe for authorization and input-handling flaws. Production monitoring keeps checking after the release. Each finds a different class of defect, so no single one replaces the others.

### Where should API tests run in the delivery pipeline?

Fast functional and contract tests belong on every pull request against a preview or staging environment, because that is where a regression is cheapest to fix. Longer suites, load tests and the full security profile belong on a nightly or weekly schedule where they have time to be thorough. Production gets read-only synthetic checks and contract validation rather than a write-heavy suite.

### Do I need an OpenAPI specification to test an API?

No. A test case is a plain HTTP request with assertions, so functional, workflow, data-driven and performance tests work against any API. A specification becomes necessary for contract testing, because a contract test needs a documented shape to validate against. Once a specification exists, it also generates suites, monitors and mock servers, which is why teams that start without one tend to add one later.

## Chapters in this guide

1. [Types of API Testing, and Where Each One Fits](https://routebase.dev/guides/api-testing/types-of-api-testing/): Functional, contract, workflow, data-driven, performance, security and production tests, with what each one finds, what it misses, and where it belongs.
2. [Contract Testing vs. Integration Testing](https://routebase.dev/guides/api-testing/contract-testing-vs-integration-testing/): What a contract test proves, what an integration test proves, why neither replaces the other, and how drift opens up between a spec and the running service.
3. [Functional API Tests: What to Assert](https://routebase.dev/guides/api-testing/functional-api-tests/): How to choose assertions that catch real breakage without turning every unrelated change into a red run, plus negative cases, extraction and chaining.
4. [API Integration Testing With Scenarios](https://routebase.dev/guides/api-testing/api-integration-testing/): Testing multi-step flows where each call depends on the last, covering state between steps, asynchronous work, conditional branches and idempotency.
5. [API Test Data and Data-Driven Runs](https://routebase.dev/guides/api-testing/api-test-data/): How to make API tests deterministic, which means owning the data each run needs, cleaning up after it, and repeating one suite across many input rows.
6. [API Testing Environments, Auth and Secrets](https://routebase.dev/guides/api-testing/api-testing-environments/): Run one suite against development, staging and production without editing it, guard the environments nobody may write to, and keep credentials out of tests.
7. [API Performance Testing: Load, Stress and Soak](https://routebase.dev/guides/api-testing/api-performance-testing/): Load, stress and soak profiles, why the p95 beats the average, how to turn a latency budget into a pass or fail, and where a load test must never point.
8. [API Security Testing](https://routebase.dev/guides/api-testing/api-security-testing/): The OWASP API Security Top 10 from 2023 as a working map, authorization testing with two identities, fuzzing, and where automated scanning stops.
9. [Automated API Testing in CI/CD](https://routebase.dev/guides/api-testing/automated-api-testing-in-ci-cd/): Where the gate belongs, why exit codes are a contract, how to make a failure readable in the pipeline, and how to fix flakiness before people learn to rerun.
10. [API Monitoring and Contract Drift in Production](https://routebase.dev/guides/api-testing/api-monitoring-and-contract-drift/): Synthetic checks, contract validation on live responses, field freshness, and alert policies that people do not learn to ignore.
11. [Testing an API With an AI Agent Over MCP](https://routebase.dev/guides/api-testing/testing-with-an-agent-over-mcp/): What an agent can reliably derive from a specification, what it must not decide on its own, and why the permission model matters more than the model does.
12. [What to Look For in API Testing Tools](https://routebase.dev/guides/api-testing/api-testing-tools/): Nine criteria that decide whether a testing tool still fits in two years, written as questions to ask rather than as a list of vendors.

---

[Routebase](https://routebase.dev/) — [Sign up](https://app.routebase.dev/): Every account starts with a 14-day Pro trial — no credit card required.