Minimal referenceable error responses + reusable error examples#665
Minimal referenceable error responses + reusable error examples#665hdamker wants to merge 5 commits into
Conversation
…project#663) Replace the Generic* superset responses with minimal referenceable error responses (10 in CAMARA_common.yaml, subscription-specific ones in CAMARA_event_common.yaml) and add components/examples as shared ingredients for locally defined responses, so each API declares only the error codes it can return. Generic* responses (and CreateSubscriptionUnprocessableEntity422) stay deprecated-but-present for existing references, with two bug fixes: INVALID_TOKEN_CONTEXT removed from Generic403 (camaraproject#662) and the deprecated 409 code CONFLICT removed. API templates, the notification template, and the Design Guide error-response sections are updated to the new consumption model.
hdamker
requested review from
PedroDiez,
bigludo7,
eric-murray,
jlurien and
rartych
as code owners
| # - The `allOf` in content.application/json.schema allows a combination of both the generic ErrorInfo schema and the specific schema for this error response, | ||
| # which validates that `status` and `code` have only the specified values. | ||
| # This `allOf` is used without discriminator because it does not imply any hierarchy between the models, just 2 schemas that must be independently validated. | ||
| ####################################################### |
There was a problem hiding this comment.
Minor comment.
Maybe we can keep Lines 376-404 as commented info that may help in case an initiative needs to define API-specific error codes, or a code combination not covered by this catalogue
There was a problem hiding this comment.
Good point. Rather than restore the full commented ErrorResponseSchema block inline here — the redesign moved copy-me forms out of CAMARA_common.yaml to avoid mixing referenceable definitions with templates — the catalogue intro now points to a complete, copy-ready locally-defined response in artifacts/api-templates/sample-service.yaml and calls it out as the skeleton for API-specific codes or code combinations this catalogue does not cover. I have updated the intro comment to make that explicit in commit 82a8f1d.
| # DEPRECATED error responses | ||
| # | ||
| # The Generic* responses below are DEPRECATED as of Commonalities 0.9.0 | ||
| # and are planned for removal in the next meta-release cycle. They bundle |
There was a problem hiding this comment.
Suggestion (up to WG consideration):
Instead of being removed, would prefer to mention to have it Deprecated but documented (with # as noted text) so having them them as a consultation information but not being directly referenciable.
That is to have some guidance for API designers and API Providers implementing errors not explicitly mentioned in the API Specification. We had some discussion in the past about that point in #438
It works with examples section from pragmatical point of view, but i am afraid this generates confusion again in the future.
There was a problem hiding this comment.
Agree this is worth keeping as consultation guidance rather than losing it. That removal happens in the next meta-release cycle, not in this PR, so I have softened the banner: the Generic* responses are now noted as planned for removal or downgrade to a commented-out reference in commit 82a8f1d. The exact mechanic — delete versus keeping them as # reference text, as discussed in #438 — is a good decision for the WG to take at that removal step. Flagging it for then.
| # callbacks; local definition from GENERIC_410_GONE otherwise | ||
| # Generic422 → DeviceIdentifier422 or PhoneNumberIdentifier422 | ||
| # Generic429 → TooManyRequests429 | ||
| # Generic405, Generic406, Generic412, Generic415, Generic5xx → |
There was a problem hiding this comment.
NOTE:
- From our view 405, 406, 412, 415 and 5xx are single error code cases (not foreseen multiple codes would be allowed in the feature) so it could remain directly referenciable.
Anyway this approach will work
There was a problem hiding this comment.
You are right that there is no superset risk for these single-code statuses. The reason they are examples-only rather than referenceable responses is not the superset — it is the Design Guide's "not documented by default" guidance for 405/406/412/415/5xx. Keeping them out of the referenceable catalogue avoids nudging APIs to document statuses the guide says to omit, while the canonical examples stay available for the rare justified case. Happy to revisit if the WG wants to reconsider the "not documented by default" stance separately.
Co-authored-by: Pedro Díez García <pedro.diezgarcia@telefonica.com>
…val note Address PR camaraproject#665 review: frame the sample-service.yaml pointer as the copy-ready skeleton for codes the catalogue does not cover, and note the deprecated Generic* responses may be downgraded to a commented-out reference rather than removed outright.
2 participants
What type of PR is this?
What this PR does / why we need it:
Implements the proposed "Option 3" in #663: the
Generic*error responses bundle error codes that do not apply to every API, so every API referencing them declares error codes it can never return (#662 is the acute case).CAMARA_common.yaml: adds a catalogue of 10 minimal, directly referenceable error responses (BadRequest400,BadRequestWithRange400,Unauthenticated401,PermissionDenied403,NotFound404,IdentifierNotFound404,AlreadyExists409,DeviceIdentifier422,PhoneNumberIdentifier422,TooManyRequests429), each containing only error codes every referencing API can return, plus a newcomponents/examplessection with the canonical error examples — including those of codes without a referenceable response — for APIs defining error responses locally. Identifier-code examples come in_DEVICE/_PHONE_NUMBERwording variants; per HTTP status an intro comment lists the available responses and example ingredients.CAMARA_event_common.yaml: addsCreateSubscriptionConflict409,SinkGone410(replacingGeneric410for notification callbacks) and the subject-flavouredCreateSubscriptionDevice422/CreateSubscriptionPhoneNumber422; existing responses now reference the shared examples, removing the example duplication between the two files.Generic*responses andCreateSubscriptionUnprocessableEntity422stay in place as deprecated and content-frozen, with two bug fixes:INVALID_TOKEN_CONTEXTremoved fromGeneric403(MakeINVALID_TOKEN_CONTEXTopt-in in the sharedGeneric403#662) and the deprecated 409 codeCONFLICTremoved (enum and example).Which issue(s) this PR fixes:
Fixes #663
Fixes #662
Does this PR introduce a breaking change?
No released API references the
CAMARA_common.yamlresponses via external$ref(all released definitions hold local copies), and the deprecated responses remain valid referencing targets. Removal of the deprecated responses is proposed for the next meta-release cycle.Special notes for reviewers:
sample-notification.yamlalso switched to the new response names and now declares410(SinkGone410), which the Event Subscription and Notification Guide requires for the notification flow but the template was missing.GENERIC_400_INVALID_TOKENexample was added toCAMARA_event_common.yaml: theINVALID_TOKENcode was listed in the enum ofCreateSubscriptionBadRequest400but had no example anywhere — please review the proposed wording.GENERIC_404_IDENTIFIER_NOT_FOUNDandGENERIC_422_SERVICE_NOT_APPLICABLEnow use subject-neutral wording (previously device-worded, also for phone-number APIs); the message example in Design Guide section 3.2.2 is aligned.CAMARA_event_common.yaml; theGeneric*names are not reused, to avoid silently changing the meaning of existing references.Changelog input
Additional documentation
This section can be blank.