Quick start
curl -s https://khassida.nexusprogramming.dev/v1/khassida/9/fr.karamati.json
const BASE = "https://khassida.nexusprogramming.dev/v1";
const { data } = await fetch(`${BASE}/khassida/9/fr.karamati.json`).then((r) => r.json());
data.bayts.forEach((b) => console.log(b.number, b.text));
Endpoints
| Path | Returns |
|---|---|
/v1/meta.json | Version, counts, per-edition coverage, licence |
/v1/editions.json | The available editions and their properties |
/v1/khassidas.json | Every khassida with metadata, without text |
/v1/khassida/{number}.json | One khassida, every edition |
/v1/khassida/{number}/{edition}.json | One khassida, a single edition |
/v1/edition/{edition}.json | The whole corpus in one edition |
Every response carries the same envelope, so a client only ever unwraps
data:
{ "code": 200, "status": "OK", "data": { … } }
A missing khassida or edition is a plain HTTP 404 from the web server, not an envelope with an error code. The full description is in openapi.yaml.
Editions
| Identifier | Language | Unit | Coverage |
|---|---|---|---|
| Loading… | |||
Every khassida is translated into French, English and Italian
by the three bayt-level *.karamati editions — 193 of 193. The two
verse-level editions are a partial extra that aligns translation to the
hemistich rather than the full line. Spanish is not yet available.
Verses and bayts
Arabic poetry is written in bayts — full lines made of two
hemistichs — and this dataset keeps both units. verses holds one
entry per hemistich, which is the unit the Arabic text and the transcription
are aligned to and what you want for following a recitation.
bayts holds one entry per full line, with verseFrom
and verseTo pointing at the hemistichs it spans; a translation
that has to read as a sentence belongs here, which is why the
*.karamati editions are bayt-level.
Each edition declares its unit, so a single-edition response
returns verses for a verse-level edition and bayts
for a bayt-level one, and says which in its unit field.
Pinning and caching
This host always serves the latest build of the default branch. For a build that never moves under you, fetch a release tag through the Statically CDN:
https://cdn.statically.io/gl/nexus-programming/khassida-api/v1.0.0/v1/khassidas.json
The payloads are immutable in practice, so cache them aggressively and refresh
when sourceChecksum in /v1/meta.json changes.