zalando/restful-api-guidelines

Add guideline for common request/response schemas

tkrop opened this issue · 0 comments

tkrop commented

In the guild meeting we have discussed that we want to provide additional guidance on how to utilize a common schema definition for requests and responses. JSON Schema draft is providing support for readOnly and writeOnly flags to differentiate between properties only present in a request and properties only present in a response. The guideline has the following goals:

  1. It encourages the use of a common schema for requests and responses instead of writing to separate models where possible.
  2. It defines the default unspecified server behavior for readOnly that a server should ignore the field (opposing to rule #109 that suggest to reject fields unknown in the request object). APIs rejecting readOnly fields consequently need to specify their non-default-like behavior explicitly.