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.

[rartych]

I have added minor editorial comments in example section. Other text - LGTM.
I have also checked JSON formating with online tools:

• https://onlineyamltools.com/convert-yaml-to-json - to have schema in JSON
• https://www.jsonschemavalidator.net/ - to check response examples against the schema

[Kevsy]

HI @gmuratk -

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.

I think 'supplementary purposes' is a clear example of 'meta data', as per the examples given at JSON API: Meta Information (which is described as 'non-standard, and is intended for the document response as a whole).

But for that same reason I do not think it is appropriate for the 'partial cases' as discussed in #555, because:

• the resource representation (i.e. the request outcome) is not meta information
• we want a consistent 'standard' way to reflect partial/limited success, whereas JSON API: Meta Information states "Where included, a meta member can be used to include non-standard meta-information."
• the request may have targeted a resource collection, but the JSON API: Meta Information applies to the document (i.e. the response as a whole).

So I think this approach can be considered if we want to allow some non-standard meta information that applies to the whole response, but not for limited/partial success cases.

[rartych]

@Kevsy the PR description looks out-dated as PR evolved:

• reference to JSON API: Meta Information is removed
• now it proposes Success Responses with Meta Information that allows some non-standard meta information that applies to the whole success response

[rartych]

I guess, that API definitions should enumerate meta values to make it easier for machine processing.

[Kevsy]

Thanks @rartych -

@Kevsy the PR description looks out-dated as PR evolved:

• reference to JSON API: Meta Information is removed
• now it proposes Success Responses with Meta Information that allows some non-standard meta information that applies to the whole success response

The reference has been removed, but the design of JSON API: Meta Information is still there. For the reason I give above I don't believe that is appropriate for partial/limited success scenarios.

I guess, that API definitions should enumerate meta values to make it easier for machine processing.

That's my point: a 'meta' field that was intended for free entry is not appropriate here. I agree that API's should define an enumeration for response values/text that indicate partial success, but that should be a formal part of the response definition.

[PedroDiez]

should not be oneOf?

[gmuratk]

Given the #567 (comment) I had changed it to anyOf.

[PedroDiez]

This will break clients in API stable versions, for instance (Device Reachability Status):

200 OK
{
"lastStatusTime": "2024-02-20T10:41:38.657Z",
"reachable": false
}

200 OK
{
"meta": { "Request was valid. Unable to provide details." }
}

Because meta is not added as an optional field over "regular" response schema but as another response option

[PedroDiez]

In line with Issue#555 comment Let's imagine an API that adopts this model, in the same way an API Provider can adopt 200 with "meta" response, how would be guaranteed that an API provider is free to not adopt it

[hdamker]

Thanks for the proposal and the good discussion it triggered around the "limited success / no result" topic from #555.

After reviewing the discussion here and in #555, I don't think this approach solves the underlying problem:

The issue in #555 is about how to model business-level outcomes (success, failure, partial, unknown) for valid 2xx requests in a consistent, interoperable way. The proposed meta container is an untyped, optional escape hatch. It does not give API designers or consumers a clear pattern for these outcomes.

I share @Kevsy's concern that a free-form meta field is not appropriate for communicating meaningful status information. As he noted, such information should have consistent, enumerated values rather than arbitrary metadata. I also agree with @PedroDiez that the anyOf approach introduces backward-compatibility risks when response shapes can change unpredictably.

I would recommend closing this PR and addressing #555 via guidance in the CAMARA API Design Guide. The guidance should be based on explicit, typed outcome fields (e.g. status / verificationResult + optional …Reason / …Message) rather than via a generic meta container.

I am preparing a PR along these lines.

[gmuratk]

Closed. Addressed via PR #578