rest-guide icon indicating copy to clipboard operation
rest-guide copied to clipboard

Add rule that request and response bodies MUST be valid against the OpenAPI contract

Open jpraet opened this issue 3 months ago • 2 comments

Maybe this is self-evident, but this isn't specifically mentioned anywhere in the REST guide, and non-compliance is a major interoperability issue.

All request bodies emitted from clients, and all response bodies emitted from servers (including problems) must be valid against the OpenAPI contract.

jpraet avatar Sep 18 '25 13:09 jpraet

I propose to add this to: [oas-contra]

Interactions with a REST API (i.e. both requests and responses) MUST be valid with respect to the constraints in its OpenAPI description. When receiving invalid requests, APIs SHOULD return a badRequest problem with an issue of type urn:problem-type:belgif:input-validation:schemaViolation

pvdbosch avatar Sep 19 '25 10:09 pvdbosch

TODO: also response validation guideline

If a REST API validates its responses before returning it, invalid response should result in a 500 Internal Server Error, or a client that calls an external API - 502 Bad Gateway (if exposed that there's an external API being called)

pvdbosch avatar Sep 19 '25 13:09 pvdbosch