HYPERFLEET-978 - feat: Add PUT command for internal status endpoints (2/2)

Author: ma-hill

CLAUDE.md

@@ -46,7 +46,7 @@ The `aliases.tsp` symlink determines which provider types are active. The `build
 
 Status endpoints are split:
 - `services/statuses.tsp` - GET operations (external clients)
-- `services/statuses-internal.tsp` - POST operations (internal adapters only)
+- `services/statuses-internal.tsp` - PUT operations (internal adapters only)
 
 The split allows generating different API contracts per audience. Only `statuses.tsp` is imported by default.
 

README.md

@@ -110,7 +110,7 @@ Contains service definitions that generate the OpenAPI specifications:
 
 - **`services/clusters.tsp`** - Cluster resource endpoints
 - **`services/statuses.tsp`** - Status resource endpoints (GET only - public API)
-- **`services/statuses-internal.tsp`** - Status write endpoints (POST/PUT - internal API, see below)
+- **`services/statuses-internal.tsp`** - Status write endpoints (PUT - internal API, see below)
 - **`services/nodepools.tsp`** - NodePool resource endpoints
 
 #### Public vs Internal API Split
@@ -120,7 +120,6 @@ The status endpoints are split into two files to support different API consumers
 | File | Operations | Audience | Included in Build |
 |------|------------|----------|-------------------|
 | `statuses.tsp` | GET (read) | External clients | ✅ Yes (default) |
-| `statuses-internal.tsp` | POST (write) | Internal adapters | ❌ No (opt-in) |
 | `statuses-internal.tsp` | PUT (write) | Internal adapters | ❌ No (opt-in) |
 
 **Why the split?**

main.tsp

@@ -20,7 +20,7 @@ using OpenAPI;
  *
  */
 @service(#{ title: "HyperFleet API" })
-@info(#{ version: "1.0.12", contact: #{ name: "HyperFleet Team" }, license: #{ name: "Apache 2.0" ,url: "https://www.apache.org/licenses/LICENSE-2.0"} })
+@info(#{ version: "1.0.13", contact: #{ name: "HyperFleet Team" }, license: #{ name: "Apache 2.0" ,url: "https://www.apache.org/licenses/LICENSE-2.0"} })
 @server("https://hyperfleet.redhat.com", "Production")
 @route("/api/hyperfleet/v1")
 namespace HyperFleet;

models/statuses/example_adapter_status.tsp

@@ -54,7 +54,7 @@ const exampleAdapterStatus: AdapterStatus = (#{
   last_report_time: "2021-01-01T10:02:00Z",
 });
 
-// Example AdapterStatusCreateRequest (for POST /clusters/{id}/statuses)
+// Example AdapterStatusCreateRequest (for PUT /clusters/{id}/statuses)
 const exampleAdapterStatusCreateRequest: AdapterStatusCreateRequest = (#{
   adapter: "validator",
   observed_generation: 1,

schemas/core/openapi.yaml

@@ -507,55 +507,10 @@ paths:
       security:
         - BearerAuth: []
   /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}/statuses:
-    post:
-      operationId: postNodePoolStatuses
-      summary: Create or update adapter status
-      description: |-
-        Adapter creates or updates its status report for this nodepool.
-        If adapter already has a status, it will be updated (upsert by adapter name).
-
-        Response includes the full adapter status with all conditions.
-        Adapter should call this endpoint every time it evaluates the nodepool.
-      parameters:
-        - name: cluster_id
-          in: path
-          required: true
-          description: Cluster ID
-          schema:
-            type: string
-        - name: nodepool_id
-          in: path
-          required: true
-          description: Nodepool ID
-          schema:
-            type: string
-      responses:
-        '201':
-          description: The request has succeeded and a new resource has been created as a result.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/AdapterStatus'
-        '400':
-          description: The server could not understand the request due to invalid syntax.
-        '404':
-          description: The server cannot find the requested resource.
-        '409':
-          description: The request conflicts with the current state of the server.
-      tags:
-        - NodePool statuses
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/AdapterStatusCreateRequest'
-      security:
-        - BearerAuth: []
     put:
       operationId: putNodePoolStatuses
-      summary: Adapter creates or updates resource nodepool status
-      description: Idempotent upsert of an adapter status for this nodepool. Use instead of POST when the adapter name is known upfront.
+      summary: Adapter creates or updates nodepool status
+      description: Adapters call this endpoint to report the status for a nodepool after each evaluation. The adapter's status entry is created if it doesn't exist, or updated if it does (upserted by adapter name). This allows HyperFleet to aggregate multiple adapter perspectives into a unified nodepool status.
       parameters:
         - name: cluster_id
           in: path
@@ -566,7 +521,7 @@ paths:
         - name: nodepool_id
           in: path
           required: true
-          description: Nodepool ID
+          description: NodePool ID
           schema:
             type: string
       responses:
@@ -631,49 +586,10 @@ paths:
       tags:
         - NodePool statuses
   /api/hyperfleet/v1/clusters/{cluster_id}/statuses:
-    post:
-      operationId: postClusterStatuses
-      summary: Create or update adapter status
-      description: |-
-        Adapter creates or updates its status report for this cluster.
-        If adapter already has a status, it will be updated (upsert by adapter name).
-
-        Response includes the full adapter status with all conditions.
-        Adapter should call this endpoint every time it evaluates the cluster.
-      parameters:
-        - name: cluster_id
-          in: path
-          required: true
-          description: Cluster ID
-          schema:
-            type: string
-      responses:
-        '201':
-          description: The request has succeeded and a new resource has been created as a result.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/AdapterStatus'
-        '400':
-          description: The server could not understand the request due to invalid syntax.
-        '404':
-          description: The server cannot find the requested resource.
-        '409':
-          description: The request conflicts with the current state of the server.
-      tags:
-        - Cluster statuses
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/AdapterStatusCreateRequest'
-      security:
-        - BearerAuth: []
     put:
       operationId: putClusterStatuses
-      summary: Adapter creates or updates resource cluster status
-      description: Idempotent upsert of an adapter status for this cluster. Use instead of POST when the adapter name is known upfront.
+      summary: Adapter creates or updates cluster status
+      description: Adapters call this endpoint to report the status for a cluster after each evaluation. The adapter's status entry is created if it doesn't exist, or updated if it does (upserted by adapter name). This allows HyperFleet to aggregate multiple adapter perspectives into a unified cluster status.
       parameters:
         - name: cluster_id
           in: path

schemas/core/swagger.yaml

@@ -655,56 +655,6 @@ paths:
       description: Returns adapter status reports for this nodepool
       operationId: getNodePoolsStatuses
       summary: List all adapter statuses for nodepools
-    post:
-      consumes:
-        - application/json
-      produces:
-        - application/json
-      parameters:
-        - description: Cluster ID
-          in: path
-          name: cluster_id
-          required: true
-          type: string
-        - description: Nodepool ID
-          in: path
-          name: nodepool_id
-          required: true
-          type: string
-        - in: body
-          name: body
-          required: true
-          schema:
-            $ref: '#/definitions/AdapterStatusCreateRequest'
-      responses:
-        '201':
-          description: >-
-            The request has succeeded and a new resource has been created as a
-            result.
-          schema:
-            $ref: '#/definitions/AdapterStatus'
-        '400':
-          description: The server could not understand the request due to invalid syntax.
-        '404':
-          description: The server cannot find the requested resource.
-        '409':
-          description: The request conflicts with the current state of the server.
-      security:
-        - BearerAuth: []
-      tags:
-        - NodePool statuses
-      description: >-
-        Adapter creates or updates its status report for this nodepool.
-
-        If adapter already has a status, it will be updated (upsert by adapter
-        name).
-
-
-        Response includes the full adapter status with all conditions.
-
-        Adapter should call this endpoint every time it evaluates the nodepool.
-      operationId: postNodePoolStatuses
-      summary: Create or update adapter status
     put:
       consumes:
         - application/json
@@ -716,7 +666,7 @@ paths:
           name: cluster_id
           required: true
           type: string
-        - description: Nodepool ID
+        - description: NodePool ID
           in: path
           name: nodepool_id
           required: true
@@ -744,10 +694,13 @@ paths:
       tags:
         - NodePool statuses
       description: >-
-        Idempotent upsert of an adapter status for this nodepool. Use instead of
-        POST when the adapter name is known upfront.
+        Adapters call this endpoint to report the status for a nodepool after
+        each evaluation. The adapter's status entry is created if it doesn't
+        exist, or updated if it does (upserted by adapter name). This allows
+        HyperFleet to aggregate multiple adapter perspectives into a unified
+        nodepool status.
       operationId: putNodePoolStatuses
-      summary: Adapter creates or updates resource nodepool status
+      summary: Adapter creates or updates nodepool status
   '/api/hyperfleet/v1/clusters/{cluster_id}/statuses':
     get:
       produces:
@@ -807,51 +760,6 @@ paths:
       description: Returns adapter status reports for this cluster
       operationId: getClusterStatuses
       summary: List all adapter statuses for cluster
-    post:
-      consumes:
-        - application/json
-      produces:
-        - application/json
-      parameters:
-        - description: Cluster ID
-          in: path
-          name: cluster_id
-          required: true
-          type: string
-        - in: body
-          name: body
-          required: true
-          schema:
-            $ref: '#/definitions/AdapterStatusCreateRequest'
-      responses:
-        '201':
-          description: >-
-            The request has succeeded and a new resource has been created as a
-            result.
-          schema:
-            $ref: '#/definitions/AdapterStatus'
-        '400':
-          description: The server could not understand the request due to invalid syntax.
-        '404':
-          description: The server cannot find the requested resource.
-        '409':
-          description: The request conflicts with the current state of the server.
-      security:
-        - BearerAuth: []
-      tags:
-        - Cluster statuses
-      description: >-
-        Adapter creates or updates its status report for this cluster.
-
-        If adapter already has a status, it will be updated (upsert by adapter
-        name).
-
-
-        Response includes the full adapter status with all conditions.
-
-        Adapter should call this endpoint every time it evaluates the cluster.
-      operationId: postClusterStatuses
-      summary: Create or update adapter status
     put:
       consumes:
         - application/json
@@ -886,10 +794,13 @@ paths:
       tags:
         - Cluster statuses
       description: >-
-        Idempotent upsert of an adapter status for this cluster. Use instead of
-        POST when the adapter name is known upfront.
+        Adapters call this endpoint to report the status for a cluster after
+        each evaluation. The adapter's status entry is created if it doesn't
+        exist, or updated if it does (upserted by adapter name). This allows
+        HyperFleet to aggregate multiple adapter perspectives into a unified
+        cluster status.
       operationId: putClusterStatuses
-      summary: Adapter creates or updates resource cluster status
+      summary: Adapter creates or updates cluster status
   /api/hyperfleet/v1/nodepools:
     get:
       produces: