aktin / aktin/MELD

Implement contract, image, job, and schedule API

Open
#8 0 comments 0 reactions 1 assignee Claimed by @simhue View on GitHub
enhancement
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.