What is API Testing? Types, Tools & How It Works

This page is the pillar of our API testing fundamentals hub. It explains what API testing is in simple words, the types of API tests, what to verify on every endpoint, and how the work actually happens, from a first request in curl to a suite that gates every pull request. If you want the automation side specifically, API test automation: what it is and how to start is the companion pillar.

What is API testing?

An API is a contract: send this request, get that response. API testing checks the contract from the outside, the way a mobile app, a partner integration or another microservice would use it. Instead of clicking through screens, a test sends an HTTP request (GET, POST, PUT, PATCH or DELETE) and verifies:

• Status code: did the API return 200, 201, 400, 404 or 500 when it should?
• Response body: does the JSON or XML contain the right data, in the shape the schema describes?
• Headers: are content type, caching and security headers correct?
• Business rules: does the API enforce them (for example, you cannot withdraw more than the balance)?
• Errors: does invalid input get a clear, consistent error instead of a 500?
• Speed: does it respond within the latency target?
• Access: does it refuse callers who lack the right credentials or permissions?

In simple words, API testing asks: "If another program calls this the way the documentation says, does it get the right answer, and does it get refused when it should?"

API tests sit in the middle of the test pyramid, above unit tests (single functions) and below UI tests (whole journeys). That position is why they are the most cost-effective layer for catching integration bugs, contract violations and logic errors. For a side-by-side of what each layer catches, see API testing vs UI testing and end-to-end testing vs API testing.

REST API testing and other protocols

The principles are the same across protocols; the contract format changes:

• REST uses resources, HTTP methods and status codes, usually described in an OpenAPI document. REST API testing checks each operation against that description and against HTTP semantics, such as PUT and DELETE being idempotent (RFC 9110).
• GraphQL sends queries to a single endpoint; the schema (SDL) is the contract, and depth limits and introspection join the checklist. See how to test GraphQL APIs.
• SOAP uses XML envelopes described by WSDL; it is still common in banking, insurance and government. See SOAP and WSDL testing.
• gRPC uses Protocol Buffers over HTTP/2 and needs proto-aware tools; the gRPC testing tools roundup covers them.
• MCP servers expose tools to AI agents over JSON-RPC; how to test MCP servers covers the handshake and tool-schema cases.

Why API testing is important

APIs carry the business logic. In most modern systems the UI is a thin layer. Pricing, permissions, data transformations and workflows live behind the API, so that is where defects originate.

Every consumer inherits API bugs. A regression in one API ripples into every app, partner and downstream service that calls it. In a microservices system, APIs are the only way services talk to each other.

API tests are fast and stable. They skip browser rendering and DOM waits, so a large API suite runs in minutes where equivalent UI coverage takes far longer. They also do not break when a button moves or a CSS class changes, because they check inputs and outputs, not pixels.

Security problems live at the API layer. The OWASP API Security Top 10 lists the most common API risks, led by broken object-level authorization: one user reading another user's data by changing an ID. Those flaws are invisible in the UI and obvious to an API test that uses two identities.

It makes shift-left practical. An API contract often exists before the code. Tests can be written, or generated, from the specification while the service is still being built, and mocks can stand in for services that are not ready. That is why API testing is the backbone of shift-left testing.

Types of API testing

Most teams start with functional and contract tests, then add the others as the API matures. Two details worth knowing:

• Functional tests split into positive tests (valid input, expected output), negative tests (invalid input, correct error), boundary tests (empty, null, maximum values) and data-driven tests (one test, many data rows).
• End-to-end API tests chain calls into a user journey (sign up, create an order, pay, refund) and assert the state carried between steps.

The nine types of API testing goes deeper into what each layer can and cannot catch.

What to test in API testing

A good API test does more than check for a 200. Use this list for every endpoint; it doubles as a set of API testing requirements for a new service:

1. Happy path: a valid request returns the documented status and body.
2. Schema: the whole response matches the schema, not just one field. Required fields are present, types and formats are right, enums hold.
3. Required and optional inputs: missing required fields fail with a 4xx; optional fields really are optional.
4. Boundaries: minimum, maximum, empty strings, zero, negative numbers, very long strings, Unicode.
5. Wrong types and malformed bodies: a string where a number belongs, broken JSON, the wrong content type.
6. Authentication: no token, an expired token and a tampered token all get 401.
7. Authorization: user A cannot read or change user B's resources (403 or 404, never 200).
8. Error format: errors are consistent and useful, and never leak stack traces.
9. Idempotency and side effects: repeating a PUT or DELETE has the same effect; a retried payment is not charged twice.
10. Pagination, sorting and filtering: no duplicates across pages, stable ordering, correct totals.
11. Rate limits: exceeding the limit returns 429 with a Retry-After header.
12. Performance: response time stays within the agreed percentile under normal load.

For a template and worked boundary examples, read how to write API test cases. Before a release, run through the API testing checklist.

How API testing works, step by step

Whether you test by hand or automate everything, the workflow has the same shape:

1. Start from the contract. If you have an OpenAPI, WSDL or GraphQL schema, you already have a test plan: every operation, parameter and response code is a case. Lint the spec first; a vague spec produces vague tests.
2. Explore manually. Send a few requests in curl or an API client to learn how the API behaves and where the documentation is wrong.
3. Write or generate the tests. Turn the cases above into repeatable tests, in code, in a client's test scripts, or generated from the spec.
4. Run against a mock, then the real service. A mock built from the spec isolates the API under test and unblocks consumers while the service is still being built.
5. Assert on the contract, not just the status. Validate every response against its schema.
6. Put it in CI/CD. Run the suite on every pull request and block the merge on failure. See API test automation with CI/CD.
7. Track coverage. Measure endpoints, methods, status codes and parameters covered, not just the number of tests. How to measure API test coverage explains the metrics.
8. Add security and performance. Layer authorization, injection and rate-limit checks, then a load smoke test, once the functional suite is stable.

Mature teams run API tests at three levels: on the developer's machine against mocks, in the CI pipeline against an ephemeral or shared test environment, and as synthetic monitors in production that call key endpoints every few minutes.

Your first API test, in curl and in pytest

Every API test is the same three steps: send a request, assert the status, assert the body. In curl that is one line per assertion:

# status code
curl -s -o /dev/null -w '%{http_code}\n' https://api.example.com/v1/orders/42

# body shape (jq -e exits non-zero when the filter is false or null)
curl -s https://api.example.com/v1/orders/42 \
  | jq -e '.id and .sku and (.qty | type == "number")'

In a test framework the same steps become a repeatable, reportable case. This one covers the happy path, a boundary, a missing field and an authorization failure:

import pytest, requests

API = "https://api.example.com"

@pytest.mark.parametrize("payload,status", [
    ({"sku": "A-1", "qty": 2}, 201),   # valid
    ({"sku": "A-1", "qty": 0}, 422),   # boundary
    ({"sku": "A-1"},           422),   # missing required field
])
def test_create_order(auth_headers, payload, status):
    r = requests.post(f"{API}/v1/orders", json=payload, headers=auth_headers)
    assert r.status_code == status

def test_create_order_requires_auth():
    assert requests.post(f"{API}/v1/orders", json={}).status_code == 401

If you need an API to practise on, public APIs for testing lists sandboxes that are safe to hammer.

API testing tools

There is no single best API testing tool; there is a best tool for each job. The categories:

How to choose, in short: if your team writes Java, REST Assured fits the build you already have; if non-developers need to contribute, a GUI client or a no-code platform fits better; if you maintain OpenAPI specs, generating tests from them removes most of the authoring work. Our best API testing tools roundup compares more than twenty options by job, with pricing and licence for each, and API testing frameworks compared helps you pick a code-first framework.

Where Shift-Left API fits: it is our API testing platform. It reads an OpenAPI, WSDL or GraphQL schema (or requirement documents) and generates functional, negative and boundary tests you review and run in CI. It tests REST, SOAP and GraphQL on every plan, including Server-Sent Events streams; JSON-RPC 2.0, MCP server and WebSocket-RPC testing are on the Trial and Enterprise editions. It does not test gRPC, so a gRPC estate still needs a proto-aware tool. Load testing and API security testing are paid add-ons.

API testing challenges and best practices

Test data. Tests that share data collide. Create the data each test needs through the API, clean it up afterwards, and keep fixtures out of shared environments. See test data management best practices.

Unstable dependencies. Payment gateways and third-party APIs fail for reasons unrelated to your code. Stub them in functional and contract tests (API mocking for parallel development) and keep the real-dependency tests in a separate, less frequent stage.

Authentication. OAuth 2.0, JWT, API keys and mTLS make setup error-prone. Write one reusable helper (or auth profile) that fetches and refreshes tokens, keep credentials in your CI secret store, and use dedicated test accounts.

Versioning. When an API evolves, test the new version and prove old consumers still work. Contract tests are the cheapest way to do that; API contract testing covers consumer-driven and schema-first approaches.

Flaky tests. Timeouts, race conditions and shared state cause intermittent failures that erode trust. Isolate data, avoid ordering dependencies, and find out why a test failed before adding a retry.

Maintenance. Hard-coded values and copy-pasted requests turn into debt as the API grows. Use request builders, shared assertions and data-driven tests, or generate the baseline from the spec.

The practices that matter most, in priority order:

• Treat the API specification as the source of truth and keep it in version control.
• Validate the whole response against the schema, not only the status code.
• Test error paths as thoroughly as happy paths.
• Run the suite on every pull request; nightly-only runs find bugs a day late.
• Use two identities in every authorization test.
• Keep the PR suite under about ten minutes by sharding and tagging.
• Name tests after the business rule ("customer cannot check out with an expired card"), not the HTTP call.
• Review coverage by endpoint, method and status code every sprint.

API testing best practices expands each of these into a pattern with examples. If you are preparing for a QA or SDET role, API testing interview questions collects the questions these topics turn into.

More from the API Testing hub

Every guide in this hub, grouped by format. The API Testing hub page has the full list.

Guides and concepts

• API Functional Testing: Techniques, Examples and Automation

Checklists, templates and test cases

• API Test Cases for Login: 40 Cases with Expected Results
• Pagination Test Cases for APIs: 36 Cases with a Free CSV
• API Testing Examples: 22 Real Test Cases With Code

API testing FAQ

What is API testing in simple words?

API testing means calling an API the way another program would and checking that it answers correctly. You send a request, then check the status code, the data in the response, the headers, how long it took, and whether it refuses requests it should refuse. No screen or browser is involved, which is why API tests are fast and stable.

Why is API testing important?

Most business logic lives behind APIs, and every app, partner and microservice that calls an API inherits its bugs. Testing at the API layer catches those defects before they reach any consumer, runs much faster than UI testing, breaks less often when the interface changes, and is where authorization and input-validation flaws are easiest to find.

What should you test in API testing?

For each endpoint, test the status code, the response body against its schema, the important headers, business rules, error responses for invalid input, authentication and authorization, and response time. Then test the edges: missing and extra fields, boundary values, pagination, rate limits, and what happens when a dependency fails.

What is API testing in QA?

In QA, API testing is the service-layer part of the test strategy. It sits between unit tests, which developers write for single functions, and UI tests, which check whole user journeys. QA engineers use it to verify requirements and business rules directly against the service, usually with a mix of exploratory requests and automated regression suites that run in CI.

What is REST API testing?

REST API testing is API testing for services that follow REST conventions over HTTP: resources addressed by URL, standard methods such as GET, POST, PUT, PATCH and DELETE, and standard status codes. Tests usually validate requests and responses against an OpenAPI description and check that each method behaves as HTTP semantics say it should, for example that PUT and DELETE are idempotent.

Is API testing the same as backend testing?

Not quite. Backend testing covers everything behind the interface: databases, queues, jobs and internal logic. API testing focuses on the contract a service exposes to its consumers. The two overlap, because an API test often proves backend behaviour through the API, but backend testing also includes checks that never touch an endpoint, such as migrations or batch jobs. For tools that cover both, see backend testing tools.

Sources and further reading

• OpenAPI Specification: the normative format for describing HTTP APIs.
• RFC 9110, HTTP Semantics: the definition of methods, status codes and headers.
• OWASP API Security Top 10 (2023): the reference list of API risk categories.
• Pact documentation: consumer-driven contract testing.
• Martin Fowler, "The Practical Test Pyramid": where service-level tests fit in a test strategy.

Want to try the spec-first approach on your own API? Get the free developer licence: import an OpenAPI spec, generate a first suite and run it, single user, no credit card.