Takoform
A common HTTP API for resource management.
Takoform describes how clients create, inspect, update and delete resources on a server. A Form defines a kind of resource. A Host is the server that implements it and provides the API.
Forms, Hosts and clients
A database and a worker need different settings and expose different ways to use them. Forms describe those differences. The Host API provides a common way to submit changes, follow their progress and handle conflicts or retries.
- Form
- Defines inputs, outputs, behavior and connections. Its author describes what independent implementations must agree on.
- Host
- Implements the Forms it supports, runs the resources and manages permissions, persistence and recovery. Its backend may be local or a cloud service.
- Client
- Chooses a Host and Form, sends the requested configuration and follows the result. It can be an application, CLI or infrastructure provider.
A shared API gives clients a consistent management protocol. Before using a resource, check that the Host supports the particular Form and review its available capacity, access requirements and terms.
A resource, from request to result
In this v2 example, a client asks a Host to store a key/value entry. The Form identifies the resource's behavior; spec supplies its configuration.
POST /apis/forms.takoform.com/v2/resources HTTP/1.1
Host: host.example
Authorization: Bearer <host-credential>
Content-Type: application/json
Idempotency-Key: 946eec36-4a6a-41de-8f3c-e83d2c58c246
{
"form": "https://forms.publisher.example/key-value-entry/1.0.0",
"space": "default",
"name": "greeting",
"spec": { "key": "greeting", "value": "hello" }
}Check support
Read the Host's connection and authentication details, then check support for the exact Form URL.
Submit the change
POST the resource request. The Host returns an Operation so the client can follow the accepted change.
Read the result
Follow the Operation to completion, then read the Resource's observed state and output. Acceptance alone does not mean the resource is ready to use.
Update or delete
Use the Resource UID and its current generation. If a response is lost, retry the original request with the same key within the Host's replay window.
Using and implementing Takoform
The guides below use v2. Choose v1 or v2 in the header when reading an existing implementation's API documentation.
- Use the API
Connect a client, send changes and handle their results. For Terraform or OpenTofu, use a provider that supports the chosen API and Forms.
- Define a Form
Specify the resource's inputs, observable behavior and usage contract so others can implement it.
- Implement a Host
Connect the API to an execution backend and preserve accepted operations through failures and restarts.
This site documents Takoform's common API and concepts. Individual Form specifications are published by their authors; Hosts and client tools document their own supported features.