Redesign GET /edge-cloud-zones and remove GET /clusters per issue #73

code/API_definitions/edge-application-management.yaml

@@ -87,9 +87,11 @@
     removing all associated instances.
 
     __Edge Cloud information__
-    *  __getEdgeCloudZones__ List of the operators Edge Cloud Zones and their
-    status, ordering the results by location and filtering by status
-    (active/inactive/unknown)
+    *  __getEdgeCloudZones__ Paginated list of the operators Edge Cloud Zones,
+    including their status, geographical country code and, when applicable,
+    the Kubernetes clusters available within each zone. Results can be
+    filtered by country code, Edge Cloud Provider, Edge Cloud
+    Provider-specific region and status.
 
     <!-- CAMARA:MANDATORY:authorization-and-authentication:BEGIN -->
 
@@ -201,8 +203,6 @@
     description: Application and Application Instance Lice Cycle Management
   - name: Edge Cloud
     description: Edge Cloud Zones Availability
-  - name: Cluster
-    description: Kubernetes Cluster information
   - name: App Instance CALLBACK Operation
     description: Operations for handling application instance callback notifications
   - name: App Deployment CALLBACK Operation
@@ -942,106 +942,82 @@
                 code: ABORTED
                 message: "Update conflict"
 
-  /clusters:
+  /edge-cloud-zones:
     get:
       security:
         - openId:
-            - edge-application-management:clusters:read
+            - edge-application-management:edge-cloud-zones:read
       tags:
-        - Cluster
-      summary: |
-        Retrieve a list of the available clusters filtered by the optional
-        query parameters.
+        - Edge Cloud
+      summary: Retrieve a paginated list of the provider's Edge Cloud Zones
       description: |
-        List available cluster information
-      operationId: getClusters
+        List of the provider's Edge Cloud Zones, including their status and,
+        when applicable, the Kubernetes clusters available within each zone.
+        Results can be filtered by country code, Edge Cloud Provider,
+        Edge Cloud Provider-specific region and status, and are returned as
+        a paginated collection.
+      operationId: getEdgeCloudZones
       parameters:
         - $ref: "#/components/parameters/x-correlator"
-        - name: region
+        - $ref: "../common/CAMARA_common.yaml#/components/parameters/page"
+        - $ref: "../common/CAMARA_common.yaml#/components/parameters/perPage"
+        - name: countryCode
           description: |
-            Human readable name of the geographical Edge Cloud Region of
-            the Cluster. Defined by the Edge Cloud Provider.
+            ISO 3166-1 alpha-2 country code to filter Edge Cloud Zones by
+            their geographical location, independent of any Edge Cloud
+            Provider-specific region naming.
           in: query
           required: false
           schema:
-            $ref: "#/components/schemas/EdgeCloudRegion"
-        - name: clusterRef
+            $ref: "#/components/schemas/CountryCode"
+        - name: edgeCloudProvider
           description: |
-            A globally unique identifier for the Cluster.
+            Human readable name of the Edge Cloud Provider to filter Edge
+            Cloud Zones by.
           in: query
           required: false
           schema:
-            $ref: "#/components/schemas/KubernetesClusterRef"
-        - name: edgeCloudZoneId
-          description: |
-            Edge Cloud Zone identifier.
-          in: query
-          required: false
-          schema:
-            $ref: "#/components/schemas/EdgeCloudZoneId"
-      responses:
-        "200":
-          description: |
-            Successful response, returning the cluster's information.
-            Returns an empty list if no clusters were found or none match
-            the specified query parameters.
-          headers:
-            x-correlator:
-              $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"
-          content:
-            application/json:
-              schema:
-                type: array
-                maxItems: 100
-                items:
-                  $ref: "#/components/schemas/ClusterInfo"
-        "400":
-          $ref: "#/components/responses/Generic400"
-        "401":
-          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401"
-        "403":
-          $ref: "#/components/responses/Generic403"
-  /edge-cloud-zones:
-    get:
-      security:
-        - openId:
-            - edge-application-management:edge-cloud-zones:read
-      tags:
-        - Edge Cloud
-      summary: Retrieve a list of the provider's Edge Cloud Zones and their status
-      description: |
-        List of the provider's Edge Cloud Zones and their
-        status, ordering the results by location and filtering by
-        status (active/inactive/unknown)
-      operationId: getEdgeCloudZones
-      parameters:
-        - $ref: "#/components/parameters/x-correlator"
-        - name: region
+            $ref: "#/components/schemas/EdgeCloudProvider"
+        - name: edgeCloudRegion
           description: |
-            Human readable name of the geographical Edge Cloud Region of
-            the Edge Cloud. Defined by the Edge Cloud Provider.
+            Edge Cloud Provider-specific geographical region name to filter
+            Edge Cloud Zones by. Since this value is not standardized across
+            Edge Cloud Providers, prefer filtering by countryCode when
+            provider-independent results are needed.
           in: query
           required: false
           schema:
             $ref: "#/components/schemas/EdgeCloudRegion"
         - name: status
-          description: Human readable status of the Edge Cloud Zone
+          description: |
+            Status of the Edge Cloud Zone to filter by. If omitted, Edge
+            Cloud Zones are returned regardless of their status.
           in: query
           required: false
           schema:
-            $ref: "#/components/schemas/EdgeCloudZoneStatus"
+            type: string
+            enum:
+              - active
+              - inactive
+              - unknown
       responses:
         "200":
           description: |
-            Successful response, returning the
-            Available Edge Cloud Zones.
+            Successful response, returning a paginated list of the Edge
+            Cloud Zones matching the specified query parameters.
           headers:
             x-correlator:
               $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"
+            x-total-count:
+              $ref: "../common/CAMARA_common.yaml#/components/headers/x-total-count"
+            x-total-pages:
+              $ref: "../common/CAMARA_common.yaml#/components/headers/x-total-pages"
+            link:
+              $ref: "../common/CAMARA_common.yaml#/components/headers/link"
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/EdgeCloudZones"
+                $ref: "#/components/schemas/EdgeCloudZoneList"
         "400":
           $ref: "#/components/responses/Generic400"
         "401":
@@ -1116,7 +1092,7 @@
                       - PERMISSION_DENIED
           examples:
             GENERIC_403_PERMISSION_DENIED:
-              description: Permission denied. OAuth2 token access does not have the required scope
+              description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
               value:
                 status: 403
                 code: PERMISSION_DENIED
@@ -1554,7 +1530,7 @@
           description: Name of the application.
         appProvider:
           $ref: "#/components/schemas/AppProvider"
         version:
           type: string
           maxLength: 64
           description: Application version information
@@ -1592,13 +1568,13 @@
                 e.g. in Github repo.
             imagePath:
               $ref: "#/components/schemas/Uri"
             userName:
               type: string
               maxLength: 64
               description: |
                 Username to acces the Helm chart, docker-compose
                 file or VM image repository
             credentials:
               type: string
               maxLength: 2048
               writeOnly: true
@@ -1647,7 +1623,7 @@
               - componentName
               - networkInterfaces
             properties:
               componentName:
                 type: string
                 maxLength: 64
                 description: Component name must be unique with an application
@@ -1735,26 +1711,24 @@
 
     ClusterInfo:
       type: object
-      description: Kubernetes cluster information
+      description: |
+        Kubernetes cluster information. Returned nested within the Edge
+        Cloud Zone it belongs to, so identifiers already provided by the
+        enclosing Edge Cloud Zone (zone id, region) are not repeated here.
       required:
         - name
-        - provider
+        - edgeCloudProvider
         - clusterRef
-        - edgeCloudZoneId
       properties:
         name:
           type: string
           maxLength: 64
           description: |
-            Name of the Cluster, scoped to the Provider
-        provider:
-          $ref: "#/components/schemas/AppProvider"
+            Name of the Cluster, scoped to the Edge Cloud Provider
+        edgeCloudProvider:
+          $ref: "#/components/schemas/EdgeCloudProvider"
         clusterRef:
           $ref: "#/components/schemas/KubernetesClusterRef"
-        edgeCloudZoneId:
-          $ref: "#/components/schemas/EdgeCloudZoneId"
-        edgeCloudRegion:
-          $ref: "#/components/schemas/EdgeCloudRegion"
         version:
           type: string
           maxLength: 64
@@ -1768,27 +1742,45 @@
             $ref: "#/components/schemas/KubernetesNodePool"
           minItems: 1
 
+    CountryCode:
+      type: string
+      pattern: ^[A-Z]{2}$
+      minLength: 2
+      maxLength: 2
+      description: |
+        ISO 3166-1 alpha-2 country code representing the geographical
+        location of the Edge Cloud Zone, independent of any Edge Cloud
+        Provider-specific region naming.
+      example: "GB"
+
     EdgeCloudProvider:
       type: string
       maxLength: 64
       description: Human readable name of the Edge Cloud Provider.
 
     EdgeCloudRegion:
       type: string
       maxLength: 64
       description: |
         Human readable name of the geographical Edge Cloud Region of
         the Edge Cloud. Defined by the Edge Cloud Provider.
 
-    EdgeCloudZones:
-      type: array
-      items:
-        $ref: "#/components/schemas/EdgeCloudZone"
-      minItems: 1
-      maxItems: 100
+    EdgeCloudZoneList:
+      type: object
       description: |
-        A collection of Edge Cloud Zones where the Application Provider can
-        instantiate an Application Instance.
+        A paginated collection of Edge Cloud Zones where the Application
+        Provider can instantiate an Application Instance.
+      required:
+        - edgeCloudZones
+        - pagination
+      properties:
+        edgeCloudZones:
+          type: array
+          maxItems: 100
+          items:
+            $ref: "#/components/schemas/EdgeCloudZone"
+        pagination:
+          $ref: "../common/CAMARA_common.yaml#/components/schemas/Pagination"
 
     EdgeCloudZoneId:
       type: string
@@ -1812,6 +1804,7 @@
         - edgeCloudZoneId
         - edgeCloudZoneName
         - edgeCloudProvider
+        - countryCode
       properties:
         edgeCloudZoneId:
           $ref: "#/components/schemas/EdgeCloudZoneId"
@@ -1823,8 +1816,19 @@
           $ref: "#/components/schemas/EdgeCloudProvider"
         edgeCloudRegion:
           $ref: "#/components/schemas/EdgeCloudRegion"
+        countryCode:
+          $ref: "#/components/schemas/CountryCode"
+        clusters:
+          description: |
+            Kubernetes clusters available within this Edge Cloud Zone, when
+            applicable. Omitted or empty if the Edge Cloud Provider does not
+            offer Kubernetes clusters in this zone.
+          type: array
+          maxItems: 100
+          items:
+            $ref: "#/components/schemas/ClusterInfo"
 
     EdgeCloudZoneName:
       type: string
       maxLength: 64
       description: |
@@ -1898,12 +1902,12 @@
           description: Definition of Kubernetes primary Network
           type: object
           properties:
             provider:
               description: CNI provider name
               type: string
               maxLength: 64
               example: cilium
             version:
               description: CNI provider version
               type: string
               maxLength: 64