5.5.2.9 Submissions
The Submissions domain of farm. Submissions to official bodies, such as milk recording: the farm asks for a submission over a period in a format, reviews the generated file, sends it and records the recipient's answer. Disputed facts are sent with their winning value and keep their data issue open; a later change marks the submission outdated. It is one API, with its own contract and its own version.
5.5.2.9.1 Versions¶
| Version | Status | Prod URL | Contract |
|---|---|---|---|
v1 |
Proposed | https://farm.moonitoring.com/submissions/v1 |
submissions/v1/openapi.yaml |
The resources follow the data model. Adds SubmissionFormat, the export mappings we offer, and the response handshake. Reading submissions uses farm.official_submissions.submit because the catalog has no read capability for them.
5.5.2.9.2 Operations¶
Every operation names who calls it and the capability it checks (x-moonitoring-audience, x-moonitoring-capability in the contract); every capability is in the catalog of the data model (req 1002, 1006). Lists are paged by cursor, writes that create something carry an Idempotency-Key, errors are Problem Details.
| Operation | Request | Who | Capability |
|---|---|---|---|
| List submission formats | GET /formats |
Organization users, staff or clients | none: any member of the Organization |
| List a farm's submissions | GET /organizations/{organization_id}/submissions |
Organization users, staff or clients | farm.official_submissions.submit or farm.canonical_data.read_all |
| Prepare a submission | POST /organizations/{organization_id}/submissions |
Organization users | farm.official_submissions.submit |
| Read a submission | GET /submissions/{submission_id} |
Organization users, staff or clients | farm.official_submissions.submit or farm.canonical_data.read_all |
| Download the file | POST /submissions/{submission_id}/payload-url |
Organization users, staff or clients | farm.official_submissions.submit or farm.canonical_data.read_all |
| Send a submission | POST /submissions/{submission_id}/send |
Organization users | farm.official_submissions.submit |
| Record the recipient's answer | POST /submissions/{submission_id}/response |
Organization users | farm.official_submissions.submit |
5.5.2.9.3 Contract v1¶
Proposed version
v1 is a proposal for review: its endpoints, errors and capabilities were designed from the requirements and the flows and are not confirmed. It leaves proposal with its first release; from then on it changes only as described in Every API Is Versioned.