Redesign GET /edge-cloud-zones and remove GET /clusters per issue #73 - #79
Open
DLondonoD wants to merge 2 commits into
Open
Redesign GET /edge-cloud-zones and remove GET /clusters per issue #73#79DLondonoD wants to merge 2 commits into
DLondonoD wants to merge 2 commits into
Conversation
…araproject#73 Per issue camaraproject#73's analysis of both list endpoints against the CAMARA Design Guide (including the pagination guide at Commonalities/documentation/CAMARA-API-Design-Guide.md#41-pagination): Fix (mandatory per issue): - ClusterInfo.provider renamed to edgeCloudProvider, now referencing EdgeCloudProvider instead of the incorrect AppProvider (Application Provider != Edge Cloud Provider running the cluster). - Removed 500/503 from the endpoint, and restricted 400/403 to only INVALID_ARGUMENT/PERMISSION_DENIED via new local Generic400/403 response objects, per the rationale already applied for issue camaraproject#72 (5xx not documented by default; OUT_OF_RANGE/INVALID_TOKEN_CONTEXT irrelevant to this API). Consider (adopted): - Combined GET /clusters into GET /edge-cloud-zones: removed the standalone /clusters path, getClusters operation, its dedicated security scope and the now-unused 'Cluster' tag. EdgeCloudZone gains an optional 'clusters' array (ClusterInfo items, without the redundant edgeCloudZoneId/edgeCloudRegion fields already provided by the enclosing zone), populated when the zone has Kubernetes clusters available. - Added pagination support per the Commonalities pagination guide: page/perPage query params (ref'd from CAMARA_common.yaml), x-total-count/x-total-pages/link response headers, and a new EdgeCloudZoneList response schema (replacing the bare EdgeCloudZones array) wrapping items + the common Pagination object. - Added a new CountryCode schema (ISO 3166-1 alpha-2) and countryCode query parameter, replacing the previous edge-cloud-provider-specific 'region' filter with a standardized, interoperable one. EdgeCloudZone gains a required 'countryCode' property; the existing free-text edgeCloudRegion field is kept as provider-specific descriptive info. - Added an edgeCloudProvider query parameter to filter zones by provider. - Removed the 'default: unknown' from the status query parameter (now defined inline instead of -ing EdgeCloudZoneStatus, whose default remains appropriate for the response object) so omitting the filter returns zones of any status instead of defaulting to 'unknown' only. Updated getEdgeCloudZones.feature accordingly (new schema references, countryCode/edgeCloudProvider/pagination scenarios, removed the region-filter scenario, added a no-default-status scenario and a 400 invalid-page scenario) and deleted getClusters.feature, since the operation no longer exists. Fixes camaraproject#73
Per the Commonalities pagination guide, the 'items' array name in the paginated response schema is API-specific, not mandatory - renamed EdgeCloudZoneList.items to edgeCloudZones for clarity in this API's context. Updated the .feature file's property references accordingly. Also restored the ability to filter by edgeCloudRegion, lost when 'region' was replaced by the new standardized countryCode filter. The EdgeCloudZone schema still exposes edgeCloudRegion as a provider-specific descriptive field, so it makes sense to keep it filterable alongside countryCode: countryCode for provider-independent results, edgeCloudRegion when finer, provider-specific granularity is needed. Added the corresponding query parameter, operation/API description updates, and a getEdgeCloudZones.feature scenario.
DLondonoD
requested review from
FabrizioMoggio,
JoseMConde,
Kevsy,
gainsley,
maheshc01 and
seralogar
as code owners
August 5, 2026 15:20
seralogar
approved these changes
Aug 6, 2026
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 fixes the design of the
GET /edge-cloud-zonesandGET /clusterslist endpointsper the issues identified:
Fixes (mandatory):
ClusterInfo.providerrenamed toedgeCloudProvider, now referencingEdgeCloudProviderinstead of the incorrect
AppProvider(an Application Provider is the API consumer, not theentity running the Kubernetes cluster).
500/503and restricted400/403to onlyINVALID_ARGUMENT/PERMISSION_DENIED, per the same rationale already applied for Review documented error response codes #72.Design changes (adopted from the "Consider" list):
GET /clustersintoGET /edge-cloud-zones: removed the standalone/clusterspath, the
getClustersoperation, its dedicated security scope and the now-unusedClustertag.EdgeCloudZonegains an optionalclustersarray, populated when the zone has Kubernetesclusters available.
com/camaraproject/Commonalities/blob/r4.3/documentation/CAMARA-API-Design-Guide.md#41-pagination):
page/perPagequery params,x-total-count/x-total-pages/linkresponse headers, and a newEdgeCloudZoneListresponse schema wrapping anedgeCloudZonesarray (named per-API rather thanthe generic
items, as the guide allows) plus the commonPaginationobject.countryCodefilter (ISO 3166-1 alpha-2), independent of Edge CloudProvider terminology, as a new required
EdgeCloudZone.countryCodeproperty. The previousprovider-specific
edgeCloudRegionfilter is kept alongside it (not removed) for casesneeding finer, provider-specific granularity.
edgeCloudProviderfilter to filter zones by provider.default: unknownfrom thestatusquery parameter, so omitting it nowreturns zones of any status instead of only
unknownones.Which issue(s) this PR fixes:
Fixes #73
Special notes for reviewers:
getClusters.featurewas deleted since the operation no longer exists;getEdgeCloudZones. featurewas updated with new scenarios forcountryCode,edgeCloudProvider,edgeCloudRegion,pagination, and the no-default-status behavior.
Changelog input
release-note Redesign GET /edge-cloud-zones to include paginated results and, when applicable,
Kubernetes cluster information; remove the standalone GET /clusters endpoint; add countryCode and
edgeCloudProvider filters; fix ClusterInfo's provider field to reference the Edge Cloud Provider
instead of the Application Provider.
Additional documentation
This section can be blank.
docs