Host API overview
Host API is the HTTP API for creating, reading, updating and deleting resources defined by Forms. A Host is an implementation serving this API. It installs definitions for the Forms it supports, accepts settings according to them and returns resource state.
This guide is non-normative. The Host API v1 specification defines implementation requirements.
Discover the endpoint
Request /.well-known/takoform/v1 to obtain supported API versions and endpoints. Use the returned API endpoint to construct resource operation URLs.
| Purpose | URL |
|---|---|
| Discovery | GET /.well-known/takoform/v1 |
| API root | /apis/forms.takoform.com/v1 |
| Resource operations | {api}/resources/{formGroup}/{kind}/{name} |
Discovery returns one API version. The API endpoint uses the same origin as the discovery URL. User information, queries, fragments and percent encoding are not allowed in that endpoint. Plain HTTP is limited to loopback development.
Software release numbers are separate from the API version forms.takoform.com/v1. Updating a library does not change the API URL.
API operations
The API defines discovery, validation, preparation, create/update/read/delete/import, observation, concurrency control, asynchronous operations and errors.
The common API does not define the meaning of an individual Form or which backend a Host uses. Resource-specific operations belong to the Interfaces and Bindings referenced by the Form.
Select an exact Form
All four FormRef fields identify one definition. This illustrates the shape:
{
"apiVersion": "forms.example.com",
"kind": "ExampleResource",
"definitionVersion": "0.3.0",
"schemaDigest": "sha256:<64 lowercase hexadecimal characters>"
}All four values need to match. latest, an omitted version or a name-only reference cannot substitute for them. An unresolved definition produces form_unknown before the resource is changed.
Identity and concurrency
uid: identity issued on creation. Deleting and recreating the resource changes it.generation: advances with user-requested state changes, starting at1.revision: also advances with Host-returned state/output changes, starting at1.
Creation uses If-None-Match: *. Updates, observation, preparation of existing resources and deletion use the concurrency preconditions specified for each operation.
Missing required preconditions produce invalid_argument; stale generations produce generation_conflict, stale revisions produce revision_conflict, and a recreated resource produces uid_mismatch. Check the operation inventory for details.
Errors
operations-v1.json defines error codes, HTTP statuses and retryability. Implementations cannot add their own common error codes.
Schemas and operation inventory
| File | Contents |
|---|---|
operations-v1.json | Operations and concurrency checks |
host-discovery.schema.json | Discovery |
form-ref.schema.json | FormRef |
host-api-wire.schema.json | Resources and errors |
operation.schema.json | Asynchronous operation records |
host-support-profile.schema.json | Host support |
Read next
- Getting started — package verification and API examples.
- Common model — definitions, packages and Snapshots.
- Conformance checks — reading reports.
- Versioning and compatibility — detailed rules.