Success Responses with Meta Information

[gmuratk]

What type of PR is this?

• enhancement/feature

What this PR does / why we need it:

Current CAMARA API Design Guide does not define option to define handling for 'limited' success responses for valid requests with partial fulfillment. In addition, while the ErrorInfo structure allows for 4xx/5xx responses to provide insights, there is no option to provide such insights for the 2xx, success responses. This PR introduces a new subsection in the Design Guide referencing the JSON API: Meta Information for a conditional optional property to be considered by the API Designers for sharing meta data, either for supplementary purposes or to handle partial cases, such as indeterminate situations.

Which issue(s) this PR fixes:

Fixes #555

Does this PR introduce a breaking change?

• Yes
• No

Special notes for reviewers:

Changelog input

 release-note
- Conditional Optional Meta Information Property definition in API Designs

Additional documentation

Obsoletes #557

docs

[rartych]

@gmuratk thanks for the new proposal.
I am not sure if meta should be included (even as optional) in API-specific response

If so, then the oneOf at the top level creates two mutually exclusive options:

1. Must have meta (and nothing else required)
2. Must have fieldA and fieldB (but meta becomes forbidden)

This means when fieldA and fieldB are present, meta cannot be included, which isn't what you want.

JSON:API v1.0 — Section 7.5: Meta Information requires meta to be an object.
But we can omit the reference to JSON:API and have CAMARA own definition.

[gmuratk]

Thanks @rartych !

1. For the meta we can use an object structure, or as you said just leave the reference out.
2. If I change the oneOf to anyOf and I think that will allow for meta to be included along with API-specific response. Let me know if you disagree.