docs: add draft public and event contracts - #9
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f58893bd44
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| required: [id, tenant_id, device_model_id, status] | ||
| properties: | ||
| corelink_device_id: {type: string, format: uuid} | ||
| id: {type: string, format: uuid} |
There was a problem hiding this comment.
The public Device response exposes its canonical identifier as id, while the repository's public-contract rule explicitly defines it as corelink_device_id; related provisioning, command, path, and event fields also use device_id. SDKs generated from this document will therefore omit the promised public identifier and establish an incompatible naming convention at the contract boundary. Use corelink_device_id consistently throughout the public contract.
Useful? React with 👍 / 👎.
| required: [device_model_id] | ||
| properties: | ||
| device_model_id: {type: string, format: uuid} | ||
| name: {type: string, maxLength: 255, nullable: true} |
There was a problem hiding this comment.
Under OpenAPI 3.1, nullable: true no longer extends type: string to include JSON null, so standards-compliant validators and generators will reject null despite the schema clearly intending to allow it. This affects both DeviceCreate.name here and Device.name later in the document; declare the type as a union including null instead.
Useful? React with 👍 / 👎.
| type: object | ||
| additionalProperties: false | ||
| required: [event_id, event_type, occurred_at, tenant_id, data] | ||
| required: [id, type, version, occurred_at, tenant_id, correlation_id, payload, metadata] |
There was a problem hiding this comment.
For command-event payloads, this required list allows an envelope with no device_id, even though the channel is documented as partitioned by that identity and the property is defined below. Consumers validating against this contract therefore cannot rely on every command event identifying its device, which prevents safe routing or correlation; add the canonical device identifier to required.
Useful? React with 👍 / 👎.
| '401': {$ref: '#/components/responses/Unauthorized'} | ||
| '403': {$ref: '#/components/responses/Forbidden'} | ||
| '404': {$ref: '#/components/responses/NotFound'} | ||
| /api/v1/tenants/{tenant_id}/devices/{corelink_device_id}/commands: | ||
| '409': {$ref: '#/components/responses/Conflict'} |
There was a problem hiding this comment.
When an authenticated actor lacks permission for the tenant in this path, provisioning has the same 403 authorization outcome as the neighboring device and command operations, but this response list exposes only 401 and 409. Generated clients and mocks consequently treat a legitimate tenant-authorization response as undocumented, contrary to the repository rule that every operation define authorization failures; add the shared Forbidden response.
Useful? React with 👍 / 👎.
| '401': {$ref: '#/components/responses/Unauthorized'} | ||
| '403': {$ref: '#/components/responses/Forbidden'} | ||
| '404': {$ref: '#/components/responses/NotFound'} | ||
| '409': {$ref: '#/components/responses/Conflict'} |
There was a problem hiding this comment.
When an authenticated caller with access to a tenant supplies an unknown device UUID, the provisioning and command operations need to report that the nested resource does not exist, but neither response set defines a 404 and there is no reusable not-found response. Generated clients and mocks will therefore treat this routine lookup outcome as an undocumented response; add a problem-shaped 404 response to the nested operations.
Useful? React with 👍 / 👎.
| post: | ||
| tags: [Devices] | ||
| summary: Register a canonical device | ||
| operationId: createDevice | ||
| x-corelink-stability: stable | ||
| tags: [devices] |
There was a problem hiding this comment.
For a client retry after a timeout, the tenant and device creation POSTs provide no idempotency mechanism, unlike the provisioning and command POSTs defined below. The same logical request can therefore create a duplicate resource or produce a conflict whose result cannot be correlated with the original call, despite the repository rule that operations define idempotency; apply the shared IdempotencyKey parameter to both creation operations.
Useful? React with 👍 / 👎.
1 participant
What changed
Validation
git diff --checkpasses.Scope note
These are draft contracts for the presentation slice, not a claim of full API compatibility or release stability.