API Testing
The UI is just the tip of the iceberg. API testing validates the entire submerged mass: business logic, data integrity, security, and performance — all without opening a browser.
1 The Hook
An NZ fintech startup had a beautiful mobile app. Their UI tests passed every night. Their Cypress suite had 400 tests. Their dashboard was green. Then they launched.
Within a week, customers reported that transfers between accounts were failing intermittently. The UI showed a success message. The money never moved. Worse: the API had a race condition where two simultaneous transfers could debit one account twice and credit the other once. A customer lost $14,000 before anyone noticed.
The root cause? The team had never tested the transfer API directly. All their tests went through the UI, which added artificial delays that masked the timing issue. The API itself had zero automated tests.
APIs are where the real business logic lives. The UI is a thin presentation layer. If the API is wrong, the UI cannot save you. If the API is right, the UI can be rebuilt without touching core functionality.
In modern architectures — microservices, serverless, headless CMS — the API is the product. Testing it thoroughly is not optional.
2 The Rule
API testing validates that an application programming interface meets expectations for functionality, reliability, performance, security, and data contract compliance — independently of any user interface.
API tests are faster, more stable, and more maintainable than UI tests. They run in milliseconds, not seconds. They are less brittle because they do not depend on DOM structure, CSS selectors, or browser rendering.
3 The Analogy
Testing the engine of a car without looking at the paint job.
You can have a beautiful car with flawless paint, leather seats, and a perfect dashboard. But if the engine stalls at 80 km/h, the car is useless. UI testing checks the paint and seats. API testing checks the engine, transmission, and brakes. A car buyer who only inspects the exterior is making a terrible decision. A QA team who only tests the UI is doing the same.
4 API Types and Architectures
REST (Representational State Transfer)
The dominant standard. Uses HTTP methods (GET, POST, PUT, DELETE) and JSON payloads. Stateless, cacheable, and resource-oriented. Example: GET /api/v1/customers/123 returns customer data as JSON.
GraphQL
A query language where the client specifies exactly what data it needs. Single endpoint, precise responses, reduces over-fetching. Testing challenge: validate that the schema matches what the client expects, and that complex nested queries do not cause performance issues (N+1 problem).
SOAP (Simple Object Access Protocol)
XML-based, rigidly structured, commonly found in enterprise and government systems (including some NZ government integrations). Uses WSDL for contract definition. Testing requires XML validation, WS-Security headers, and often specific tooling like SoapUI.
gRPC and WebSockets
gRPC uses Protocol Buffers for high-performance internal service communication. WebSockets enable real-time bidirectional communication (chat, live updates). Both require specialised testing approaches beyond standard HTTP clients.
5 What to Test in an API
A comprehensive API test strategy covers six dimensions:
1. Functional Testing
- Does the endpoint return the correct data for valid requests?
- Does it create, update, and delete resources correctly?
- Does it handle query parameters, pagination, sorting, and filtering?
- Does it enforce business rules (e.g., cannot withdraw more than balance)?
2. Input Validation & Negative Testing
- What happens with missing required fields?
- What happens with invalid data types (string where number expected)?
- What happens with extremely long strings, special characters, or Unicode?
- What happens with SQL injection or XSS payloads in JSON fields?
- Does it return proper HTTP status codes (400 for bad input, 404 for missing resource)?
3. Authentication & Authorisation
- Can unauthenticated users access protected endpoints?
- Can users access other users' data (IDOR / BOLA)?
- Does the token expire and refresh correctly?
- Are role-based permissions enforced at the API layer (not just UI)?
4. Performance & Reliability
- Response time under expected load
- Timeout behaviour (does it fail gracefully or hang indefinitely?)
- Rate limiting (does it throttle excessive requests?)
- Concurrent request handling (race conditions, deadlocks)
5. Error Handling & Logging
- Are error messages helpful but not revealing (no stack traces to clients)?
- Do error responses follow a consistent schema?
- Are errors logged server-side with sufficient context for debugging?
- Does the API return correct Content-Type headers even for errors?
6. Data Integrity & State Management
- After a POST, does a GET return the created data accurately?
- After a DELETE, does a GET return 404?
- Are database transactions atomic (all-or-nothing)?
- Does the API handle eventual consistency correctly (if applicable)?
6 Tools in Action
Postman is the most popular API testing tool for manual and semi-automated testing. Collections let you organise requests, environments manage variables, and Tests scripts (JavaScript) enable assertions.
Postman also supports Newman for CLI execution, making it CI/CD friendly.
REST Assured brings the elegance of behaviour-driven syntax to Java. Perfect for teams already using Java/Spring.
Karate uses Gherkin syntax (Given-When-Then) but does not require step definitions. Extremely readable for non-technical stakeholders.
Choosing a tool: Postman for exploratory testing and rapid prototyping. REST Assured for Java-based CI/CD pipelines. Karate for readable, maintainable BDD tests. k6 or JMeter for API performance testing (see Performance Testing).
7 Contract Testing
In microservices architectures, teams own different services that communicate via APIs. Contract testing ensures that the consumer's expectations match the provider's implementation — without requiring both services to be running simultaneously.
Consumer-Driven Contract Testing
The consumer (client) defines what it needs from the API. The provider verifies it can fulfil that contract. If the provider changes something the consumer relies on, the contract test fails before deployment. Tools: Pact (industry standard), Spring Cloud Contract.
Why it matters: In a large NZ enterprise with 50 microservices, integration testing every combination is impossible. Contract tests give you confidence that services will work together without spinning up the entire ecosystem.
8 Common Mistakes
🚫 Testing only the happy path
I used to think: If 200 OK works, the API is fine.
Actually: APIs fail in interesting ways. Empty arrays, null fields, expired tokens, malformed JSON, and concurrent requests all expose different bugs. Your test suite should have more negative tests than positive ones.
🚫 Hard-coding data that changes
I used to think: Use customer ID 123 in every test.
Actually: If customer 123 is deleted or modified, all tests break. Use test data factories, setup/teardown hooks, or mock servers. Each test should create its own data and clean up after itself.
🚫 Ignoring headers and metadata
I used to think: Only the response body matters.
Actually: Content-Type, Cache-Control, X-Request-ID, CORS headers, and rate-limit headers are all part of the API contract. A missing Content-Type header can break client parsers. A missing CORS header can block frontend requests entirely.
🚫 Testing against production
I used to think: Production is the source of truth.
Actually: POST and DELETE tests against production create real data and real damage. Use a dedicated test environment, or mock the API with tools like WireMock, Mountebank, or Postman mock servers.
9 Now You Try
Scenario: You are testing an NZ rental property API. The endpoint POST /api/v1/listings creates a new property listing with fields: address, suburb, rent_per_week, bedrooms, bathrooms, and available_date.
Design a test plan with at least 6 test cases:
- 2 positive tests (valid data, boundary values)
- 2 negative tests (invalid data, missing fields)
- 1 security test (authorisation)
- 1 performance test (response time expectation)
10 Self-Check
Click each question to reveal the answer.
Q1. Why are API tests generally more stable than UI tests?
They do not depend on browser rendering, DOM structure, or CSS selectors. APIs return structured data (JSON/XML) with predictable schemas. UI tests break when a button moves; API tests break when the contract changes.
Q2. What is the difference between REST and GraphQL?
REST uses multiple endpoints with fixed response structures. GraphQL uses a single endpoint where the client specifies exactly which fields to return. GraphQL reduces over-fetching but introduces risks like complex nested queries causing N+1 performance problems.
Q3. What is contract testing and why is it important for microservices?
Contract testing verifies that API consumers and providers agree on the interface. It catches breaking changes early without requiring all services to be running together. Essential when dozens of teams deploy independently.
Q4. Why should you not test against production APIs with POST/DELETE operations?
They create and destroy real data. A DELETE test could remove a real customer. A POST test could spam real users with notifications. Always use isolated test environments or mocks for write operations.