How to validate an API

Validate an API by doing two things in tandem: enforce request validation on the server or gateway to reject malformed inputs early, and verify responses against a stable contract (for example, JSON Schema) in automated tests and CI so breaking changes surface before release. This combination is widely documented and helps prevent unnecessary backend calls, improves reliability, and catches regressions fast (AWS API Gateway request validation; Assertible: test API responses with JSON Schema).

What API validation covers

Effective validation spans both sides of the contract:

• Request validation: check required parameters, types and basic formats before hitting business logic. Placing this at the gateway, middleware, or controller reduces attack surface and keeps handlers clean (Treblle: add request validation).
• Response validation: assert that the API still matches what clients expect by validating structure and types against a schema in automated tests (Assertible: JSON Schema checks).

Validate requests early on the server or gateway

Where to place request checks

Prefer validation as early as possible. Managed gateways can reject invalid inputs and return a 400 without invoking your backend, which reduces unnecessary calls and centralizes basic checks (AWS API Gateway request validation). In application code, put reusable rules in middleware or framework-provided validation layers rather than mixing them into controllers (Treblle: add request validation).

Rules that deliver high value

• Required fields: fail fast if mandatory body, query, header, or path params are missing (AWS API Gateway request validation).
• Types and formats: validate integers vs strings, and common formats like email, UUID, and ISO 8601 date-time to stop malformed but syntactically valid JSON (Treblle: add request validation).
• Value constraints: min/max lengths or ranges to prevent out-of-bounds inputs (Treblle: add request validation).
• Allow-listing: explicitly accept only known fields and structures to avoid surprise parameters; many practical guides favor allow-lists over deny-lists for clarity and safety (Treblle: add request validation).

Quickly test auth and structures before automating

Before wiring automation, use an independent client (for example, Postman) to confirm authentication and capture real request and response structures. Start with a simple GET to verify connectivity, then iterate on body shape and headers. Saving actual structures helps downstream tooling process data accurately (Jitterbit tutorial: validate a REST API). For example, some APIs, like Jira in Jitterbit’s walkthrough, return 204 No Content for successful updates and deletes, which you’ll see during manual validation and can then encode into tests (Jitterbit tutorial: validate a REST API).

Validate responses against a contract

Use JSON Schema in automated tests

Define the expected shape and types of each endpoint and assert responses against that schema in your test suite. When the response drifts (a missing required field, a type change), the test fails with a clear error, making regressions easy to triage (Assertible: test API responses with JSON Schema). Even UI-led test tools can validate response structure; for example, Playwright tests can assert types for each field in the payload (CodeSignal: validating API responses).

Map schema assertions to CI

Run schema checks automatically on pull requests. Keep them fast and focused so they guard contracts without slowing unrelated work. Fail the build on contract violations to surface breaking changes early (Assertible: JSON Schema checks).

Decide what to validate and when

• Be strict on public or shared contracts and safety-critical endpoints (payments, identity). Lighter rules can be acceptable for fast-moving internal endpoints until they stabilize (Treblle: add request validation).
• Iterate: start with required fields and types, then add formats and ranges as you see real-world failures (Treblle: add request validation).

Common pitfalls

• Only testing responses: without server-side request checks, you can still persist bad data. Pair both sides.
• Loose or deny-list rules: underspecified schemas create false confidence; explicit allow-listed schemas make intent obvious (Treblle: add request validation).
• Flaky CI: unstable fixtures or changing sample data cause noise. Pin test data and declare only truly required fields in schemas (Assertible: JSON Schema checks).

Related reading

• What is API versioning? Practical guidance for small teams
• Webhook signature verification explained

FAQ

What status code should I return on validation failure?

Returning 400 Bad Request for malformed or missing parameters is a common approach; some teams use 422 Unprocessable Entity when the JSON is well-formed but fails business validation. Choose one and document it for clients (Treblle: add request validation; AWS API Gateway request validation).

Do I need both request and response validation?

Yes. Request validation protects your backend and data integrity; response validation protects clients by detecting breaking changes early (Treblle: add request validation; Assertible: JSON Schema checks).