Implement contract, image, job, and schedule API
- Dominant language
- Python
- Stars
- 0
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
## Description
This issue tracks the design, implementation, testing, and documentation of the proposed API.
The API definition is currently subject to review. Payload schemas, authentication details, identifiers, and lifecycle behavior remain TBD.
## Proposed API surface
| Endpoint | Method | Description | Request | Response | Priority |
|---|---|---|---|---|---|
| `/health` | GET | Check server health | — | 200 OK — server is healthy
503 Service Unavailable — server is unhealthy | High |
| `/version` | GET | Retrieve the server version | — | 200 OK with server version | Low |
| `/contracts` | GET | List all uploaded contracts and associated image status | — | 200 OK with list of contracts | Medium |
| `/contracts` | POST | Create a new contract and pull its referenced image (async) | Contract body
Optional Docker registry API key in header | 201 Created — contract created and image already available
202 Accepted — contract created and image pull initiated
400 Bad Request — contract malformed
401 Unauthorized — API key missing or invalid when registry authentication is required
403 Forbidden — API key lacks permission to pull the image
409 Conflict — contract already exists
502 Bad Gateway — image registry unavailable | Critical |
| `/contracts/{contractId}` | GET | Retrieve a specific contract and associated image status | — | 200 OK with contract
404 Not Found — contract does not exist | Medium |
| `/contracts/{contractId}` | DELETE | Delete a contract | — | 204 No Content — contract deleted
404 Not Found — contract does not exist | Medium |
| `/contracts/{contractId}/validate` | POST | Validate a contract | — | 200 OK with validation result
404 Not Found — contract does not exist | TBD |
| `/contracts/{contractId}/inferences` | GET | List inferences for a contract | — | 200 OK with list of inferences
404 Not Found — contract does not exist | TBD |
| `/contracts/{contractId}/inferences` | POST | Start an inference (async) | Inference request body | 202 Accepted — inference started with inference ID
400 Bad Request — inference request malformed
404 Not Found — contract does not exist | TBD |
| `/contracts/{contractId}/inferences/{inferenceId}` | GET | Retrieve inference status or result archive (async) | — | 200 OK with inference status if still running
200 OK with result archive as a file object if completed
404 Not Found — contract or inference does not exist | TBD |
| `/contracts/{contractId}/inferences/{inferenceId}` | DELETE | Cancel a running inference | — | 204 No Content — inference canceled
404 Not Found — contract or inference does not exist | TBD |
| `/contracts/{contractId}/inferences/{inferenceId}/logs` | GET | Retrieve the inference log stream | — | 200 OK with log stream
404 Not Found — contract or inference does not exist | TBD |
| `/contracts/{contractId}/schedules` | GET | List schedules for a contract | — | 200 OK with list of schedules
404 Not Found — contract does not exist | TBD |
| `/contracts/{contractId}/schedules` | POST | Create a schedule for a contract | Schedule body | 201 Created — schedule created
400 Bad Request — schedule malformed or invalid
404 Not Found — contract does not exist | TBD |
| `/contracts/{contractId}/schedules/{scheduleId}` | GET | Retrieve a schedule | — | 200 OK with schedule information
404 Not Found — contract or schedule does not exist | TBD |
| `/contracts/{contractId}/schedules/{scheduleId}` | DELETE | Delete a schedule | — | 204 No Content — schedule deleted
404 Not Found — contract or schedule does not exist | TBD |
## Standard error response
All non-success responses should use the following response structure:
```json
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": {},
"requestId": "request-id"
}
}
```
The exact error codes and details remain TBD.
## Open questions
- What authentication mechanism will be used?
- What request and response schemas are required?
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.