API

The Fediversity API, under api/, is the HTTP and pub/sub backend that front-ends (such as the panel) use to manage deployments. It wraps the stateless deployment programs of the data model with queued execution, progress reporting, and authorization.

Where it sits

The API sits between front-ends and the deployment machinery:

• Front-ends submit an operator configuration over HTTP. The API validates it, enqueues a build, and runs the deployment through the effects backends (subprocess by default, or Windmill for job tracking).
• It streams build progress and deployment-state changes back over Centrifugo WebSocket channels (fediversity.builds.<deployment_id>.<build_id> and fediversity.deployments.<deployment_id>), rather than making clients poll.
• It maintains a small state store of deployments and build history: a SQLite file, or PostgreSQL when API_DATABASE_URL is set.

Deployment identifiers are opaque to the API. The panel uses the primary key of its Django Deployment model.

Map of this site

Each group below has an overview page that lists its pages.

• Design -- the design of the API and its reasons: the transport, the deployments and their deletion, authorization, the schema sources, the actions, migrations, domains, the update policy, usage and the build queue.
• Guides -- how to run the API locally, set up Incus, pin the schema, run the tests, send authorized requests from the Swagger UI and extend the base model.
• Reference -- the services.fediversity-api options, the environment variables, the wire surface, the error codes, the database and the flake attributes.
• Specifications -- what api must do, and the principles that apply to all changes in api/.