Fediversity API

Feature Specification: Application Catalog

Created: 2026-09-23

Status: Implemented

Input: Reconstructed from the code of api/ at 0bf4ecd36, api/specification.md, and the commit that added the catalog.

User Scenarios & Testing (mandatory)

User Story 1 - List the applications (Priority: P1)

A front-end shows the applications and components that a deployment can have, with a title, a description, a home page and an icon. It gets them from api, and does not keep its own list. The listing is wider than the form: it also holds supporting components that no schema names.

Why this priority: a front-end with its own list shows applications that core does not give, or misses new ones.

Independent Test: unit tests check that the listing has one entry for each entry in the catalog of core.

Acceptance Scenarios:

  1. Given the catalog of core, When the client lists it, Then api returns each entry with its metadata, and whether the form configures it, whether the operator can turn it off, and whether it has its own subdomain.
  2. Given an entry with an icon, When the client asks for the icon, Then api returns the image with a tag from the hash of its content.
  3. Given an unknown entry, or an entry without an icon, When the client asks for its icon, Then api reports it as not found.

Edge Cases

  • A client sends the current tag: api reports the icon as not modified.
  • An entry without artwork has no icon in the listing.

Requirements (mandatory)

Functional Requirements

  • FR-001: api MUST serve the catalog of the default source, made at build time from core. The icons MUST come from the package source of each component, and serving one MUST NOT need an eval.
  • FR-002: The catalog MUST be public, because it contains no data of a deployment.
  • FR-003: api MUST tag an icon with the hash of its content, not with its modification time, and MUST allow clients to keep it in a cache for a short time.
  • FR-004: The build MUST fail when an application of the form has no artwork.

Key Entities

  • Catalog entry: an application or component of core: name, metadata, flags and icon.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: A front-end shows all applications of core without a hard-coded list.

Assumptions

  • The catalog follows the default source. The catalog of another source is not served.

Known Deviations

None.