- PHP 92.4%
- Shell 7.6%
|
|
||
|---|---|---|
| .forgejo/workflows | ||
| .githooks | ||
| .github | ||
| bin | ||
| docs | ||
| public | ||
| scripts | ||
| sql | ||
| src | ||
| tests | ||
| .gitattributes | ||
| .gitignore | ||
| CHANGELOG.md | ||
| cliff.toml | ||
| composer.json | ||
| composer.lock | ||
| LICENSE | ||
| phpcs.xml.dist | ||
| phpstan.neon.dist | ||
| phpunit.xml.dist | ||
| README.md | ||
| renovate.json | ||
| ROADMAP.md | ||
Directorium API
Cache-first HTTP API for the traditional Roman liturgy — Introíbo ad altáre Dei.
The Directorium API is the authoritative, versioned (/v1) HTTP service over the Directorium Core
engine. Its responses are a pure function of (date, system, calendar, office, hour, language) and
therefore immutable per key — pre-generated as static JSON for hot paths, computed on demand for
cold dates, and fronted by Cloudflare with long, immutable TTLs, ETags, and a data-version stamp.
Corrections bump the data-version and purge the edge cache.
It issues and meters API keys per tenant (quotas + rate limits) and is consumed by the directorium.app website and admin, the Ordo WordPress plugin, and future apps.
Status
Pre-release — v0.1.0 in progress. See the roadmap.
Stack
PHP + MySQL on DreamHost, Cloudflare in front, cache-first. MySQL holds only API keys, tenants, aggregate usage counters, and the search index — never a row per request. Node is build-time only; no Python.
Development
Work branches off develop, lands via squash PRs with Conventional-Commit titles, and releases are
cut automatically by release-please. The engine is consumed as the directorium/core Composer
dependency (pinned by composer.lock); the API adds no liturgical logic of its own. The
architecture is documented in docs/design/api-architecture.md.
composer install # pulls in directorium/core
composer check # PSR-12 lint + PHPStan + PHPUnit — the CI gate
php -S 127.0.0.1:8080 -t public public/index.php
# → GET /v1/day/2026-09-03?calendar=sspx
# → GET /v1/month/2026-09
# → GET /v1/year/2026
# → GET /v1/meta (supported systems, calendars, languages, range)
# → GET /v1/health
# Pre-generate the static tier for a year range (data-version-namespaced):
php bin/generate-static.php 2024 2030 ./build/static
Access control (API keys, quotas, rate limits) is off until a key store is
configured — set DIRECTORIUM_DB_DSN (schema in sql/schema.sql)
and manage tenants/keys with php bin/api-key.php (tenant / issue / rotate /
revoke). Health, discovery, and the policies (/v1/aup, /v1/terms) stay public.
Admin actions (POST /v1/admin/purge, /rebuild) exist only when
DIRECTORIUM_ADMIN_TOKEN is set; edge purge targets Cloudflare (DIRECTORIUM_CF_ZONE /
DIRECTORIUM_CF_TOKEN), a no-op otherwise.
Licence
© 2026 Directorium. Licensed under AGPL-3.0-or-later (see LICENSE). The compiled calendar dataset is released under CC0.