feat: Enhance extension resource ownership and metadata handling (#279)

- Updated descriptions in extensions.yaml to clarify owner reference requirements for system-scoped resources.
- Modified create and update functions in sys_extension_resources.go to streamline response handling and improve error management.
- Adjusted client methods to return the correct resource types and updated associated tests for consistency.

Signed-off-by: Bailin He <bahe@equinix.com>

Author: bailinhe

openapi/v1alpha1/components/schemas/extensions.yaml

@@ -123,10 +123,10 @@ ExtensionResourceMetadataOwnerRef:
       enum:
         - group
         - user
-      description: Type of owner (group or user)
+      description: Type of owner. For system-scoped resources, only 'group' is supported.
     id:
       type: string
-      description: ID of the owner
+      description: ID of the owner (group ID or user ID)
   required:
     - kind
     - id
@@ -136,8 +136,7 @@ ExtensionResourceMetadataCreateRequest:
   properties:
     owner_ref:
       $ref: '#/ExtensionResourceMetadataOwnerRef'
-  required:
-    - owner_ref
+  description: Metadata for creating an extension resource. The owner_ref field is optional.
 
 ExtensionResourceMetadataUpdateRequest:
   type: object
@@ -147,7 +146,7 @@ ExtensionResourceMetadataUpdateRequest:
     resource_version:
       type: integer
       format: int64
-      description: Version number for optimistic concurrency control
+      description: Version number for optimistic concurrency control. Required for updates to ensure the resource hasn't been modified.
 
 ExtensionResourceStatus:
   type: object

openapi/v1alpha1/paths/extensions.yaml

@@ -351,6 +351,10 @@ extension-resources:
     description: |
       Creates a new extension resource. The extension, kind, and version must be specified in the request body.
       The kind should use the singular slug form of the extension resource definition.
+      
+      **Owner Reference:**
+      - For system-scoped resources, you can optionally specify a group owner via metadata.owner_ref.kind (must be "group") and metadata.owner_ref.id (group UUID)
+      - User-scoped resource ownership is not yet supported
     requestBody:
       required: true
       content:
@@ -377,7 +381,17 @@ extension-resources:
             schema:
               $ref: '../components/schemas.yaml#/ExtensionResource'
       '400':
-        $ref: '../components/responses.yaml#/BadRequest'
+        description: Bad Request (invalid owner_ref.kind, validation error, or resource constraint violation)
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                error:
+                  type: string
+                  examples:
+                    - "owner_ref.kind must be 'group' with system extension resources"
+                    - "validation error: resource constraint violation"
       '401':
         $ref: '../components/responses.yaml#/Unauthorized'
       '403':
@@ -410,8 +424,12 @@ extension-resources-id:
       Updates an existing extension resource. The extension, kind, and version must be specified in the request body.
       The kind should use the singular slug form of the extension resource definition.
       
+      **Optimistic Concurrency Control:**
       Optionally, you can provide metadata.resource_version for optimistic concurrency control to ensure the resource
-      hasn't been modified since it was last read. You can also update status.messages to track resource state changes.
+      hasn't been modified since it was last read.
+      
+      **Status Updates:**
+      You can also update status.messages to track resource state changes.
     parameters:
       - name: resource-id
         in: path
@@ -431,6 +449,9 @@ extension-resources-id:
             kind: "database"
             version: "v1"
             metadata:
+              owner_ref:
+                kind: "group"
+                id: "550e8400-e29b-41d4-a716-446655440000"
               resource_version: 1234567890
             spec:
               name: "production-db"
@@ -447,7 +468,17 @@ extension-resources-id:
             schema:
               $ref: '../components/schemas.yaml#/ExtensionResource'
       '400':
-        $ref: '../components/responses.yaml#/BadRequest'
+        description: Bad Request (invalid owner_ref.kind, validation error, or resource constraint violation)
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                error:
+                  type: string
+                  examples:
+                    - "owner_ref.kind must be 'group' with system extension resources"
+                    - "validation error: resource constraint violation"
       '401':
         $ref: '../components/responses.yaml#/Unauthorized'
       '403':
@@ -591,8 +622,8 @@ resources-id:
           type: string
         description: Resource ID
     responses:
-      '204':
-        description: No content
+      '202':
+        description: Resource deleted
     security:
       - bearerAuth: []
       - oauth2ClientCredentials: ['governor:extensionresources:delete']

pkg/api/v1alpha1/extension_resources.go

@@ -105,33 +105,7 @@ func (r *Router) createExtensionResource(c *gin.Context) {
 		}
 	}
 
-	res := createSystemExtensionResource(c, r.DB, r.EventBus, extension, erd, req.Spec, ownerID)
-	if res == nil {
-		return
-	}
-
-	resp := &ExtensionResource{
-		Extension: req.Extension,
-		Kind:      req.Kind,
-		Version:   req.Version,
-		Spec:      req.Spec,
-		Metadata: ExtensionResourceMetadata{
-			OwnerRef:        req.Metadata.OwnerRef,
-			CreatedAt:       res.CreatedAt.Format(time.RFC3339),
-			ID:              res.ID,
-			ResourceVersion: res.ResourceVersion,
-		},
-		Status: ExtensionResourceStatus{
-			UpdatedAt: res.UpdatedAt.Format(time.RFC3339),
-		},
-	}
-
-	resp.Status.Messages = make([]json.RawMessage, len(res.Messages))
-	for i, msg := range res.Messages {
-		resp.Status.Messages[i] = json.RawMessage(msg)
-	}
-
-	c.JSON(http.StatusCreated, resp)
+	createSystemExtensionResource(c, r.DB, r.EventBus, extension, erd, req.Spec, ownerID)
 }
 
 func (r *Router) updateExtensionResource(c *gin.Context) {
@@ -194,34 +168,5 @@ func (r *Router) updateExtensionResource(c *gin.Context) {
 		r.Logger.Debug("current resource version", zap.Int64("resource_version", *rv))
 	}
 
-	res := updateSystemExtensionResource(c, r.DB, r.EventBus, extension, erd, rid, req.Spec, msgs, rv)
-	if res == nil {
-		return
-	}
-
-	resp := &ExtensionResource{}
-
-	resp.Extension = req.Extension
-	resp.Kind = req.Kind
-	resp.Version = req.Version
-	resp.Metadata.CreatedAt = res.CreatedAt.Format(time.RFC3339)
-	resp.Metadata.ID = res.ID
-	resp.Metadata.ResourceVersion = res.ResourceVersion
-
-	if res.OwnerID.Valid && res.OwnerID.String != "" {
-		resp.Metadata.OwnerRef = ExtensionResourceMetadataOwnerRef{
-			Kind: ExtensionResourceOwnerKindGroup,
-			ID:   res.OwnerID.String,
-		}
-	}
-
-	resp.Spec = json.RawMessage(res.Resource)
-	resp.Status.UpdatedAt = res.UpdatedAt.Format(time.RFC3339)
-
-	resp.Status.Messages = make([]json.RawMessage, len(res.Messages))
-	for i, msg := range res.Messages {
-		resp.Status.Messages[i] = json.RawMessage(msg)
-	}
-
-	c.JSON(http.StatusAccepted, resp)
+	updateSystemExtensionResource(c, r.DB, r.EventBus, extension, erd, rid, req.Spec, msgs, rv)
 }