Remove irrelevant/undocumented-by-default error codes per issue #72 - #78
Open
DLondonoD wants to merge 3 commits into
Open
Remove irrelevant/undocumented-by-default error codes per issue #72#78DLondonoD wants to merge 3 commits into
DLondonoD wants to merge 3 commits into
Conversation
…aproject#72 Per CAMARA API Design Guide 3.2.1, error statuses 5xx are not documented by default in the API specification unless a relevant use case justifies it. This API has no such use case for the operation-level 500/503 responses (they were the plain generic server-error boilerplate), so all 15 operations' 500/503 responses are removed. Callback 410/429 responses are kept, since they are justified by the notification/callback flow context per the same guideline and the CAMARA Event Subscription and Notification Guide. Also introduced local, API-scoped Generic400/403/404 response objects (replacing the direct $ref to CAMARA_common.yaml's generic ones) that restrict the documented error codes to only those that actually apply to this API's business logic: - 400: only INVALID_ARGUMENT (dropped OUT_OF_RANGE - EAM has no range-constrained query/body fields that would justify this code) - 403: only PERMISSION_DENIED (dropped INVALID_TOKEN_CONTEXT - EAM is a B2B management API with no per-request identity binding to an OAuth2 token to validate against) - 404: only NOT_FOUND (dropped IDENTIFIER_NOT_FOUND - this code is device-identification specific per the Design Guide's own example; EAM never identifies a 'device', only apps/instances/deployments/ clusters/zones, already covered by NOT_FOUND) 401 (UNAUTHENTICATED only) and 409 (already using API-specific inline ALREADY_EXISTS/INCOMPATIBLE_STATE/ABORTED responses, never CONFLICT) were already correct and left untouched. Fixes camaraproject#72
Verified every .feature file's tested status codes against the actual responses documented per operation in the spec. Found 3 more phantom error scenarios testing a 404 that the corresponding operation never declares - all are plain collection GETs with only optional query filters, which per REST/CAMARA semantics return 200 with an empty list when nothing matches, not 404: - getApps.feature: no filters at all, 404 never applied - getAppDeployments.feature: 404 filtered-by-appId scenario left behind when 404 was removed from the operation's YAML in PR camaraproject#56 (8755fb2) - getClusters.feature: 404 filtered-by-region scenario, same pattern All other operations' tested status codes (200/201/202/204, 400, 401, 403, 404 on by-id operations, 409 with API-specific codes) were verified to match exactly what edge-application-management.yaml documents for each operationId; no other discrepancies found.
DLondonoD
requested review from
FabrizioMoggio,
JoseMConde,
Kevsy,
gainsley,
maheshc01 and
seralogar
as code owners
August 5, 2026 14:04
seralogar
reviewed
Aug 6, 2026
Co-authored-by: Sergi <sergialonsogarcia@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What type of PR is this?
correction
What this PR does / why we need it:
Reviews and trims the documented error response codes per the Commonalities Design Guide section on [Standardized Use
of CAMARA Error Responses](https://github.com/camaraproject/Commonalities/blob/r4.3/documentation/CAMARA-API-Design-
Guide.md#321-standardized-use-of-camara-error-responses):
500/503from all 15 operations. Per the guide, 5xx statuses are not documented by default unlessa relevant use case justifies them; this API had none beyond generic boilerplate. The callback
410/429responses arekept, since they are explicitly justified by the notification flow.
400to onlyINVALID_ARGUMENT, droppingOUT_OF_RANGE— no field in this API has a pre-definednumeric/date range or filter-combination constraint that this code would apply to.
403to onlyPERMISSION_DENIED, droppingINVALID_TOKEN_CONTEXT— this code requires validatingthat an identity in the request body matches the one bound to a 3-legged access token; this is a B2B management API with
no such per-request identity binding.
404to onlyNOT_FOUND, droppingIDENTIFIER_NOT_FOUND— this code is specific to device-identification (per the guide's own example); this API never identifies a "device", only
apps/instances/deployments/clusters/zones, already covered by
NOT_FOUND.Generic400/Generic403/Generic404response objects (replacing the direct$reftoCAMARA_common.yaml's generic ones, which include the broader set of codes) to enforce the above restrictions.401(UNAUTHENTICATEDonly) and409(already using API-specificALREADY_EXISTS/INCOMPATIBLE_STATE/ABORTEDexamples, never the deprecated
CONFLICT) were already correct and left untouched.As a follow-up check, verified every
.featuretest file's tested status codes against what its operation actuallydocuments in the spec, and found (and removed) 3 more phantom
404test scenarios on collection-list operations(
getApps,getAppDeployments,getClusters) that only accept optional query filters — per REST/CAMARA semanticsthese should return
200with an empty list when nothing matches, not404. One of them was leftover from PR #56,which had already removed the
404from the operation's YAML without syncing the test.Which issue(s) this PR fixes:
Fixes #72
Special notes for reviewers:
No behavioral/runtime change to success paths — this only removes error responses that were either never justified for
this API's design or already superseded elsewhere, aligning both the OAS definition and its
.featuretest coveragewith the Design Guide.
Changelog input
release-note Remove undocumented-by-default 5xx responses and API-irrelevant error codes (OUT_OF_RANGE,
INVALID_TOKEN_CONTEXT, IDENTIFIER_NOT_FOUND) per the CAMARA Design Guide's error response guidance.
Additional documentation
This section can be blank.
docs