Test a service API in layers: assert individual requests and responses, verify data flow across component boundaries, add consumer-provider contract checks when teams depend on one another, exercise a small number of complete workflows, and test authentication and authorization against the API’s documented requirements. Automate the repeatable checks locally and in CI. No single test type proves that an API is correct, secure, and dependable in every situation.
Start with the API contract and expected behavior
Before writing tests, read the service’s current API documentation or specification. For each operation, identify its method and endpoint, required parameters and headers, request body, response shape, error behavior, and security requirements. OpenAPI security requirements can help identify which credentials or scopes an operation expects; OWASP’s REST assessment guidance recommends using API documentation to determine what to assess.
As an Amazon Associate I earn from qualifying purchases.
Check that the contract describes intended behavior rather than treating it as unquestionable truth. If tests merely repeat an incorrect specification, they can preserve a defect. Record observable outcomes that matter to callers, and avoid assertions about incidental details that the API does not promise to keep stable.
Test individual requests and responses
A request test exercises one concrete interaction. Specify the method, endpoint, authorization, parameters, headers, and body that the case requires. Assert the expected status, relevant response headers, and meaningful response fields. Include normal inputs as well as important invalid and boundary cases.
#1 Best Overall
A minimal request check with cURL
This example shows the shape of a request test; replace the host, path, token, and expected values with those defined by your service’s contract.
curl --fail-with-body
-H "Authorization: Bearer $API_TOKEN"
-H "Accept: application/json"
"https://api.example.com/v1/accounts/123"To make this a test rather than a manual inspection, capture the response and assert the status and contractually meaningful fields in your test runner. Keep secrets out of source control, and use test credentials with only the access the case needs.
Choose assertions that remain useful
- Assert status codes, required headers, and fields that are part of the API contract.
- For error cases, verify the documented error shape and relevant status rather than assuming every failure returns the same response.
- Cover missing, malformed, out-of-range, and unauthorized inputs where those cases matter to the operation.
- Avoid checking incidental values or the entire response when only a stable subset is relevant; overly broad assertions make tests brittle.
Postman supports request scripts for assertions and reusable request collections. Its documentation describes scripts that run before a request or after the response, which can support setup and checks. See Postman’s test scripts documentation.
Test integration boundaries and data flow
Integration tests check that components and external systems work together at their interfaces. Test sequences where one operation’s output becomes another operation’s input, and verify the data flow and relevant side effects. Use test data and authorization appropriate to the environment.
If a dependency is unavailable or needs isolation, a mock can simulate it. A mock helps test your service’s handling of a controlled interaction; it does not prove that the real dependency behaves the same way. Where the real integration is important, retain a suitable check against a controlled test service or other authorized environment. Postman’s integration-testing guidance covers workflows, collections, and mock servers: Postman integration testing.
Add consumer-provider contract tests where they fit
Contract tests address compatibility between independently developed consumers and providers. In Pact’s consumer-driven approach, the consumer records an interaction it relies on, then provider verification checks whether the provider meets that expectation. This lets teams check message compatibility without running both services together for every check.
Rank #3
Contract verification is not a substitute for functional tests of behavior outside those interactions. Keep request, integration, and workflow tests for concerns the contract does not cover. Pact explains its approach in How Pact works.
Exercise a small set of complete workflows
End-to-end API tests chain requests across multiple endpoints, passing identifiers or other response data into later calls. Choose important user or business journeys—for example, a valid sequence that creates a resource and then retrieves it—rather than trying to make every test a long workflow. Focus on failures that could emerge only across several operations. Postman describes this approach as testing complete flows across endpoints and APIs: Postman end-to-end API testing guidance.
Derive security tests from declared requirements
Build a per-operation checklist from the effective security requirements in the API specification. OWASP’s REST Assessment Cheat Sheet calls out testing with no credentials, valid credentials, and credentials that do not meet a declared requirement. Add negative authorization and input-handling cases that match the service’s actual risks.
- Try the operation without credentials when the specification requires authentication.
- Try valid credentials that satisfy the operation’s declared requirements.
- Try credentials that are valid but lack a required scope, role, or other declared condition.
Run security tests only against systems and environments you are authorized to assess. OWASP’s REST Assessment Cheat Sheet provides guidance for deriving checks from API documentation. OWASP also has an API Security Testing Framework project describing a black-box approach with endpoint discovery and checks aligned to the OWASP API Security Top 10 2023, plus other API-focused checks. Treat that page as a project overview, not independent proof of detection effectiveness; assess its current maturity and fit before adopting it operationally.
Automate the checks at useful points
Keep repeatable tests runnable locally, then choose automation triggers and suite scope that fit the team’s workflow. Fast request or contract checks can provide feedback on changes; broader workflows or security checks may belong in scheduled or pre-release runs. The exact cadence depends on the service and its delivery process.
Recommended Free Tools
Postman documents manual collection runs, scheduled runs, and CI/CD execution using Postman CLI. See running collections and command-line collection integration. Pact’s contract workflow can complement these checks where consumer-provider compatibility is a concern.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Choose an approach by the question it answers
| Approach | Primary question | Typical role |
|---|---|---|
| Request assertions | Does this operation return the expected observable result for this input? | Check status, headers, response fields, and error cases. |
| Integration tests | Do components and dependencies exchange the expected data? | Exercise boundaries and ordered interactions, using real or controlled dependencies as appropriate. |
| Consumer-provider contract tests | Does the provider preserve interactions a consumer relies on? | Check compatibility between independently developed services. |
| End-to-end API workflows | Does an important multi-operation journey work in sequence? | Chain a focused set of calls and pass outputs forward. |
| Security checks | Does access behave as the documented requirements demand? | Test missing, valid, and insufficient credentials, plus relevant negative cases. |
These layers are complementary, not interchangeable. Postman documents request scripts, collections, integration and end-to-end workflows, mocks, and automation. Pact is specifically documented for consumer-driven contract testing. When comparing tools, verify current language and framework support, collaboration needs, dependency handling, automation paths, and maintenance costs rather than assuming that one product covers every layer.
Or skip the browser setup
Service API tests usually target your own service’s contract; ScreenshotNeo is a separate website screenshot API, useful when a workflow also needs to capture a rendered page. Its one-call request is:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation. Before capture, it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the page verdict and billing status in headers. An MCP server provides screenshot tools for AI agents, and the Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Sign up for free.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Troubleshoot failing API tests
- Unexpected status or error body: Compare the request method, path, headers, body, and credentials with the operation’s documented contract; distinguish expected validation errors from service failures.
- Authentication succeeds but access is denied: Check whether the credentials meet the operation’s specific role, scope, or other security requirement, not merely whether they are valid.
- Integration tests fail intermittently: Inspect dependency availability and test data setup. Isolate unavailable or uncontrolled dependencies with mocks where appropriate, while retaining a suitable check of the real integration.
- Workflow fails at a later call: Confirm earlier responses provide the identifier or value passed forward, and that the next request uses it in the documented location.
- Tests break after harmless response changes: Narrow assertions to stable, contractually relevant fields rather than incidental response details.
- A mock-backed test passes but production integration fails: Treat the mock as evidence about your service’s handling of the simulated interaction only; verify real dependency behavior separately in an authorized environment.
Frequently Asked Questions
Should every API test be end-to-end?
No. Use focused request and boundary checks for most cases, and reserve end-to-end coverage for important multi-operation journeys.
Do contract tests replace functional tests?
No. They check consumer-provider compatibility for recorded interactions; behavior outside those interactions still needs suitable functional coverage.
Can mocks prove an external integration works?
No. They simulate controlled interactions and help isolate your service, but they do not establish how the real dependency behaves.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
