specification published #334

New issue

Open

opened 2025-05-15 20:14:11 +02:00 by kiara · 0 comments

kiara commented

2025-05-15 20:14:11 +02:00

Owner

As a front-end developer,
I want an (API) spec describing how to interact with Fediversity,
so that I can start work on front-ends.

implementation notes

see #195 for JSON-schema needed for a potential openapi spec
this schema should be the (Git-ignored) ./src/panel/configuration/schema.json from #351 (example), which given the ignore could be published using a CI pipeline
note that there will be some discrepancies between our NixOS configuration input variables versus the operator-specific deployment configurations in a multi-tenancy setting (#313) like panel, notably global run-time configurations such as ProxmoX configuration
part of this may have been implemented in panel
while our underlying logic is not very imperative, front-ends may bring along more imperative expectations such as buttons over forms, which may have use for according imperative-style REST end-points. needs #242.

open questions

e.g. authenticated end-points for CRUD actions (minus PATCH, so just GET and POST on the index, then PUT and DELETE on the separate items) of items routing to a given data model call template, mounted at say https://HOST/api/v1/deployments, plus maybe a GET on https://HOST/api/v1/deployments/1/old for distinct unstaged deployment configuration
we eventually expect a queue-like (#242) architecture, in which case the synchronous nature of HTTP requests may be less suited than the (asynchronous) WebSockets. a naive implementation could use synchronous HTTP requests (REST?). it could be valid to reuse the panel back-end for both, or have a new separate API back-end implementing asynchronous (or even both).
eventually needs to pass info on decoupled versions (#304)

**As** a front-end developer, **I want** an (API) spec describing how to interact with Fediversity, **so that** I can start work on front-ends. ## implementation notes - see #195 for JSON-schema needed for a potential openapi spec - this schema should be the (Git-ignored) `./src/panel/configuration/schema.json` from #351 ([example](https://git.fediversity.eu/kiara/fedi-goals/commit/6e385a527db6088bb6365d8682156600563edec7)), which given the ignore could be published using a CI pipeline - note that there will be some discrepancies between our NixOS configuration input variables versus the operator-specific deployment configurations in a multi-tenancy setting (#313) like `panel`, notably global run-time configurations such as ProxmoX configuration - part of this may have been implemented in `panel` - while our underlying logic is not very imperative, front-ends may bring along more imperative expectations such as buttons over forms, which may have use for according imperative-style REST end-points. needs #242. ### open questions - e.g. authenticated end-points for CRUD actions (minus `PATCH`, so just `GET` and `POST` on the index, then `PUT` and `DELETE` on the separate items) of items routing to a given data model call template, mounted at say `https://HOST/api/v1/deployments`, plus maybe a `GET` on `https://HOST/api/v1/deployments/1/old` for distinct unstaged deployment configuration - we eventually expect a queue-like (#242) architecture, in which case the synchronous nature of HTTP requests may be less suited than the (asynchronous) WebSockets. a naive implementation could use synchronous HTTP requests (REST?). it could be valid to reuse the `panel` back-end for both, or have a new separate API back-end implementing asynchronous (or even both). - eventually needs to pass info on decoupled versions (#304)