Fediversity API

Flake attributes

The flake outputs the api entrypoint (./api#...) exposes. This page is generated from the entrypoint itself every time the docs are built, so it always reflects the current outputs. Descriptions come from each attribute's meta.description.

Two kinds of attribute

The generated lists at the end of this page are api/'s own leaf outputs: api-http-stack, swagger-ui, openapi, the python tests, and so on. They are not the whole of ./api#.

Alongside them the entrypoint carries a deploy family: a full set of <group>-<effect>-<machine> attributes that provision the hosting-provider machines with api/ registered as an application. This is the api-only composition, for a downstream that wants the API service without the panel. It is exposed at the flake's top level -- the same packages/apps/ devShells/nixosConfigurations outputs core exposes, so ./api# mirrors ./core#:

nix run './api#apps.<group>-<effect>-<machine>'

How the two sets combine:

  • apps, nixosConfigurations and deploymentAttributeNames come verbatim from the rendered deploy family.
  • packages and devShells are deploy.<x> // <api's own>, so api/'s leaf attributes win. The deploy names are all group- and effect-prefixed (dev-tf-*, hosting-provider-*, operator-*, ...), so they sit alongside the flat leaf names without collision; the single overlap is devShells.default, which stays the api devShell.

The names follow core's grammar

api/ does not invent attribute names: they follow core's <group>-<effect>-<machine>[-<verb>] grammar exactly, described at https://core.pages.git.fediversity.eu/flake-attributes.html. The derivations differ, because this family is rendered from a group set that has api/ folded in, but the naming, the all/combined aggregate targets and the verbs are the same. They are not enumerated here: the family is on the order of a thousand attributes, and core's page documents the pattern rather than the list. For the flat enumeration:

nix eval --json ./api#deploymentAttributeNames

How it is built (and how to extend it)

api/ maintains no deployment topology of its own. It reuses core's pure render combinator: core ships a frontend-free base group (abundos, the hosting-provider machines with no front-end registered), and api/ folds its own components.api registration onto that base, then re-renders:

core = import ../core { inherit system sources pkgs; };
composedGroups = core.lib.foldGroupComponents core.lib.baseGroups {
  hosting-provider = [ component ];  # api's components.api fragment
};
deploy = core.lib.render { inherit system sources groups = composedGroups; };

core is downward-only (it never names a front-end leaf), so this fold happens in the leaf, by name. A downstream that wants to extend the model further -- registering another application, or adding a group -- has two routes:

  • Fold onto the frontend-free base (core.lib.baseGroups) with its own application fragment, and call the SAME core.lib.render on the result. This is the api-independent path -- the downstream names only core.

  • Extend api's pre-extended group. api/ exposes its composed group set as api.lib.composedGroups (base + api's application), so a downstream that wants api/ registered too folds only its OWN application onto that, rather than naming api's application again:

    composedGroups = core.lib.foldGroupComponents api.lib.composedGroups {
      hosting-provider = [ component ];  # only the downstream's own fragment
    };

    foldGroupComponents appends, so chaining [api] (here) then [downstream] yields the same [...base, api, downstream] merge order -- hence the same deploy -- as one fold of [api, downstream].

Either way: no fork of core, no intermediate leaf to reach around. The panel leaf is exactly such a consumer, taking the second route; see https://panel.pages.git.fediversity.eu/flake-attributes.html.

Packages

  • api-http-stack
  • asyncapi-docs: Rendered HTML documentation for the Fediversity AsyncAPI specification
  • asyncapi-spec
  • asyncapi-validate: Validates the generated Fediversity AsyncAPI specification
  • centrifugo-dev
  • default
  • docs: Generate static site docs of nix options
  • openapi
  • openapi-validate
  • swagger-ui
  • terraform-backend-dev
  • windmill-dev

Checks

  • api-asyncapi-validate: Validates the generated Fediversity AsyncAPI specification
  • api-deploy-env-apex: Assert the api node bakes the fleet's apex into an operator deploy's env, so core's cross-group names resolve there.
  • api-docs: Generate static site docs of nix options
  • api-http: Exercise the API's HTTP RPC endpoints end to end.
  • api-openapi-validate: Validate the generated OpenAPI specification.
  • api-pinned-schema: Assert a pinEffected build serves the effect's settings at the schema root, with the rename that moves a stored value there.
  • api-python-tests: Run the API's Python unit tests.
  • api-schema-parity: Assert the baked schema/renames equal core's api-schema/api-renames outputs (what a pinned module_source builds).
  • apps-api: Deploy services through the API and verify the result.
  • asyncapi-docs: Rendered HTML documentation for the Fediversity AsyncAPI specification
  • treefmt: Check that the project tree is formatted