Skip to content

fix: correct success status codes on Management Interface endpoints #196

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
matlec wants to merge 2 commits into
base: pre-draft
Choose a base branch
from
Open

fix: correct success status codes on Management Interface endpoints #196

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
79f16ba
fix: correct success status codes on Management Interface endpoints
matlec Jul 21, 2026
ac909c9
Merge branch 'pre-draft' into fix/capabilities-http-status
matlec Jul 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion system-design/specification/margo-management-interface/deployment-status.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,8 @@ POST /api/v1/clients/{clientId}/deployments/{deploymentId}/status

| Code | Description |
|------|-------------|
| 200 OK | The deployment status was added, or updated, successfully. |
| 200 OK | The deployment status was updated successfully. |
| 201 Created | The deployment status was created successfully. |
| 400 Bad Request | Missing or invalid content-digest header. Ensure the SHA256 hash of the base64-encoded payload is included. |
| 401 Unauthorized | Signature verification failed. Ensure you are signing with the correct X.509 private key. |
| 403 Forbidden | Client certificate is not trusted or has been revoked. |
Expand Down
14 changes: 7 additions & 7 deletions system-design/specification/margo-management-interface/device-capabilities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ To ensure the WFM is kept up to date, the device's client MUST send updated capa
## Route and HTTP Methods

```https
POST /api/v1/clients/{clientId}/capabilities/{deviceId}
PUT /api/v1/clients/{clientId}/capabilities/{deviceId}
DELETE /api/v1/clients/{clientId}/capabilities/{deviceId}
```
Expand All @@ -27,12 +26,13 @@ DELETE /api/v1/clients/{clientId}/capabilities/{deviceId}

| Code | Description |
|------|-------------|
| 201 OK | The device capabilities document was added, or updated, successfully |
| 200 OK | The device capabilities document was updated successfully. |
| 201 Created | The device capabilities document was created successfully. |
| 204 No Content | The device capabilities document was deleted successfully. |
| 400 Bad Request | Missing or invalid content-digest header. Ensure the SHA256 hash of the base64-encoded payload is included. |
| 401 Unauthorized | Signature verification failed. Ensure you are signing with the correct X.509 private key. |
| 403 Forbidden | Client certificate is not trusted or has been revoked. |
| 404 Not Found | POST, PUT: No client with the given `clientID` was found, or no gateway was found for the given child-device `deviceId` (see [Gateways considerations](#gateways-considerations) for more details). <br/> DELETE: No client with the given `clientID` was found or no device with the given `deviceId` was found for the client. |
| 404 Not Found | PUT: No client with the given `clientID` was found, or no gateway was found for the given child-device `deviceId` (see [Gateways considerations](#gateways-considerations) for more details). <br/> DELETE: No client with the given `clientID` was found or no device with the given `deviceId` was found for the client. |
| 422 Unprocessable Content | Request body includes a semantic error. |

## Request Body Attributes
Expand Down Expand Up @@ -196,7 +196,7 @@ A WFM client reporting the "Gateway" role MUST report its own capabilities to th
* See-thru gateway, without hosting capabilities, reporting its capabilities to the WFM:

```
POST /api/v1/clients/{clientId}/capabilities/gateway1
PUT /api/v1/clients/{clientId}/capabilities/gateway1
```
```json
{
Expand All @@ -217,7 +217,7 @@ A WFM client reporting the "Gateway" role MUST report its own capabilities to th
* See-thru gateway, with hosting capabilities, reporting its capabilities to the WFM:

```
POST /api/v1/clients/{clientId}/capabilities/gateway1
PUT /api/v1/clients/{clientId}/capabilities/gateway1
```
```json
{
Expand Down Expand Up @@ -255,7 +255,7 @@ A WFM client reporting the "Gateway" role MUST report its own capabilities to th
* See-thru gateway reporting the capabilities of a child device to the WFM:

```
POST /api/v1/clients/{clientId}/capabilities/gateway1/deviceA
PUT /api/v1/clients/{clientId}/capabilities/gateway1/deviceA
```
```json
{
Expand Down Expand Up @@ -298,7 +298,7 @@ A WFM client reporting the "Gateway" role MUST report its own capabilities to th
* See-thru gateway reporting the capabilities of a child device with deeper hierarchy to the WFM:

```
POST /api/v1/clients/{clientId}/capabilities/gateway1/path1/deviceA
PUT /api/v1/clients/{clientId}/capabilities/gateway1/path1/deviceA
```
```json
{
Expand Down
2 changes: 1 addition & 1 deletion system-design/specification/margo-management-interface/device-client-onboarding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ sequenceDiagram
Note over Client,Server: Device Client onboarding Ends
Note over Client,Server: 📡 Secure API Usage with Signed Payloads can now begin

Client->>Server: POST /clients/{clientId}/capabilities
Client->>Server: PUT /clients/{clientId}/capabilities
Server-->>Client: 201 Created
Note over Client,Server: Enrollment is complete
Note over Client,Server: 📡 Secure API Usage with Signed Payloads
Expand Down
44 changes: 7 additions & 37 deletions system-design/specification/margo-management-interface/workload-management-api-1.0.0.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,42 +86,8 @@ paths:
summary: Complete onboarding with client certificate

/api/v1/clients/{clientId}/capabilities/{deviceId}:
post:
summary: Report device capabilities
security:
- PayloadSignature: []
parameters:
- name: clientId
in: path
required: true
schema:
type: string
- name: deviceId
in: path
required: true
schema:
$ref: '#/components/schemas/DeviceId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceCapabilitiesManifest'
responses:
'201':
description: Capabilities reported successfully
'400':
description: Missing or invalid content-digest header. Ensure the SHA256 hash of the payload is included.
'401':
description: Signature verification failed. Ensure you are signing with the correct X.509 private key.
'403':
description: Client certificate is not trusted or has been revoked.
'404':
description: No client with the given `clientID` was found.
'422':
description: Request body includes a semantic error.
put:
summary: Update device capabilities (Update)
summary: Report or update device capabilities
security:
- PayloadSignature: []
parameters:
Expand All @@ -142,8 +108,10 @@ paths:
schema:
$ref: '#/components/schemas/DeviceCapabilitiesManifest'
responses:
'200':
description: Device capabilities updated successfully
'201':
description: Capabilities reported successfully
description: Device capabilities created successfully
'400':
description: Missing or invalid content-digest header. Ensure the SHA256 hash of the payload is included.
'401':
Expand Down Expand Up @@ -376,7 +344,9 @@ paths:
$ref: '#/components/schemas/DeploymentStatusManifest'
responses:
'200':
description: The deployment status was added, or updated, successfully.
description: The deployment status was updated successfully.
'201':
description: The deployment status was created successfully.
'400':
description: Missing or invalid content-digest header. Ensure the SHA256 hash of the base64-encoded payload is included.
'401':
Expand Down
Loading