An API can pass its happy-path tests and still be unsafe to release. The costly failures live at boundaries: malformed input, another user's resource, repeated requests, provider latency, partially applied state, stale webhook events, and old clients that interpret a new response differently.
Pre-release API testing should be organized around those boundaries rather than a count of endpoints.
Start with the public contract
List the routes changed by the release and capture for each:
- Method and path
- Authentication requirement
- Required role or ownership rule
- Request schema and size limit
- Success status and response schema
- Documented error codes
- Side effects
- Rate limit
- Idempotency behavior
- External dependencies
Treat headers and cookies as contract elements. A refresh endpoint that behaves differently for a web cookie and a desktop body token has two client contracts even when it shares a route.
Generate tests from the real validation schema where practical, but keep independent contract assertions. A test that imports the same schema can miss an accidental breaking change because expected and actual behavior change together.
Test schema boundaries
For each input, test more than one invalid value:
- Missing required property
- Wrong primitive type
- Empty string
- Minimum and maximum length
- One value beyond each bound
- Unknown enum value
- Extra unexpected properties
- Invalid Unicode or control characters
- Oversized body
- Invalid content type
Verify normalization. Emails may be trimmed, Unicode-normalized, and lowercased for comparison while preserving a safe display value. Paths, event names, and storage keys should use explicit character allowlists.
The response should return a stable public error code and useful message without exposing validation internals, stack traces, SQL, or filesystem paths.
Test authorization as a matrix
Authentication answers who the caller is. Authorization answers whether that identity can act on this resource.
Use at least two accounts and build a matrix:
| Actor | Own resource | Other resource | Admin resource | | --- | --- | --- | --- | | Anonymous | Denied | Denied | Denied | | User A | Allowed as designed | Denied | Denied | | User B | Allowed as designed | Denied | Denied | | Support | Explicit support scope | Explicit support scope | Denied where destructive | | Admin | Explicit admin scope | Explicit admin scope | Allowed |
Test with valid identifiers belonging to another account. Invalid identifiers only prove not-found behavior.
For sensitive actions such as license disclosure, account deletion, or release publication, test recent-password confirmation expiry and verify the token is bound to the same account and purpose.
Test state transitions and races
Model important records as a transition graph and attempt invalid edges. A release should not move from yanked back to draft through an ordinary update. A disabled lifetime license should not redeem. A rotated refresh token should not create another active token.
Send concurrent or rapidly repeated requests to operations vulnerable to races:
- Registration with the same email
- Webhook processing with the same event ID
- Refresh-token rotation
- License redemption
- Checkout session creation
- Artifact completion and publication
Database constraints and conditional updates should determine the result. An application-only read-before-write check can allow both requests through.
Exercise dependency failures
External services fail slowly as well as immediately. Test:
- Connection refused
- Timeout
- Non-JSON response
- Valid error response
- Rate limit
- Authentication rejection
- Success response missing an expected field
- Duplicate or out-of-order webhook
Bound every outbound request with a timeout. Decide whether retry is safe. A GET may be retryable, while repeating a provider mutation without an idempotency key may create duplicate state.
The client-facing error should describe the recoverable outcome, not the provider's internal response. Preserve enough sanitized metadata and a request identifier for operators to investigate.
Verify webhook authenticity and idempotency
Webhook tests need the original raw body. Parsing and reserializing JSON can change bytes and invalidate signatures.
Test:
- Correct signature
- Altered body with old signature
- Missing signature
- Wrong secret
- Stale timestamp
- Future timestamp outside tolerance
- Unsupported signing algorithm
- Duplicate provider event ID
- Event delivered out of order
- Unknown event type
Store the provider event identifier before applying business side effects or use a transactionally equivalent pattern. A successful duplicate should return quickly without sending a second email or granting a second entitlement.
For every provider, follow its documented signature format, validate the raw request body, use the configured webhook secret, and enforce timestamp tolerance when the protocol supports it.
Test response compatibility
Additive JSON fields are usually safe, but not every client ignores unknown values. Enum additions, changed nullability, status-code changes, date formats, and renamed error codes can break released desktop applications.
Keep fixtures representing supported client versions. Test the new server response against their parsers. If compatibility routes are required, give them a defined transformation and telemetry so usage can be measured without collecting sensitive payloads.
Do not silently repurpose a field. Introduce a new field, support both during migration, and remove the old field only after the supported client window closes.
Inspect side effects directly
After an API test, verify the database, email delivery record, object storage metadata, analytics event, or audit entry that should result.
A 200 response does not prove:
- The row belongs to the correct account
- A token was stored as a hash
- The email used the correct template and idempotency key
- A license remained reversibly encrypted
- The release artifact received its checksum
- An audit reason was persisted
Use an isolated test database and reset it deterministically. Avoid tests that depend on execution order or production-like shared accounts.
Verify observability is safe
Trigger failures and inspect actual logs. Confirm redaction of:
- Authorization headers
- Cookies and refresh tokens
- Passwords
- License keys
- Webhook signatures
- Request and response bodies containing personal data
- SQL or connection strings
Request identifiers should appear in both the public error and server log. Metrics should count outcomes and latency without using email addresses or high-cardinality tokens as labels.
Finish with a production-mode smoke path
Build and start the production server configuration against an isolated environment. Exercise one complete critical path, such as:
- Register and verify an account.
- Sign in and rotate the refresh credential.
- Read entitlements.
- Create a checkout or redeem a valid test entitlement.
- Process the corresponding signed webhook.
- Confirm access and email delivery metadata.
- Revoke the session.
This crosses schema validation, identity, storage, external integration, and client contract boundaries. It does not replace focused tests, but it proves the assembled application behaves like the parts.
API release confidence comes from testing what can disagree: caller and resource, schema and payload, old client and new server, local transaction and remote provider, response and side effect. Build the test plan around those seams, and a green result will carry much more evidence than a collection of happy paths.