openapi: 3.1.0
info:
  title: Khassida API
  version: 1.0.0
  summary: The Khassida of Cheikh Ahmadou Bamba as static JSON.
  description: |
    A static, read-only API: every path below is a pre-generated JSON file served
    by GitLab Pages, so only GET is supported, no authentication exists and there
    is no rate limit. A missing khassida or edition returns a plain 404 from the
    web server rather than an error envelope.

    The poems are in the public domain; the transcription and translations are
    MIT licensed. See NOTICE.md in the repository for attribution.
  license:
    name: MIT
    url: https://gitlab.com/nexus-programming/khassida-api/-/blob/main/LICENSE
servers:
  - url: https://khassida.nexusprogramming.dev
    description: Canonical host (latest build of the default branch).
  - url: https://khassida-api-43a004.gitlab.io
    description: The same site on GitLab Pages, independent of this project's DNS.
  - url: https://cdn.statically.io/gl/nexus-programming/khassida-api/v1.0.0
    description: Statically CDN, pinned to a release tag
tags:
  - name: catalogue
  - name: khassida
paths:
  /v1/meta.json:
    get:
      tags: [catalogue]
      summary: Dataset version, counts, per-edition coverage and licence
      operationId: getMeta
      responses:
        "200":
          description: Dataset metadata
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Envelope"
                  - properties:
                      data:
                        $ref: "#/components/schemas/Meta"
  /v1/editions.json:
    get:
      tags: [catalogue]
      summary: The available editions
      operationId: listEditions
      responses:
        "200":
          description: Edition catalogue
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Envelope"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Edition"
  /v1/khassidas.json:
    get:
      tags: [catalogue]
      summary: All khassida with metadata and available editions, without text
      operationId: listKhassidas
      responses:
        "200":
          description: Khassida catalogue
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Envelope"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/KhassidaSummary"
  /v1/khassida/{number}.json:
    get:
      tags: [khassida]
      summary: One khassida with every edition
      operationId: getKhassida
      parameters:
        - $ref: "#/components/parameters/number"
      responses:
        "200":
          description: The khassida, with verses and bayts carrying every edition
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Envelope"
                  - properties:
                      data:
                        $ref: "#/components/schemas/KhassidaFull"
        "404":
          description: No khassida with that number
  /v1/khassida/{number}/{edition}.json:
    get:
      tags: [khassida]
      summary: One khassida in a single edition
      description: |
        Returns `verses` for a verse-unit edition and `bayts` for a bayt-unit one;
        the `unit` field says which. Only the requested edition's text is included.
      operationId: getKhassidaEdition
      parameters:
        - $ref: "#/components/parameters/number"
        - $ref: "#/components/parameters/edition"
      responses:
        "200":
          description: The khassida in one edition
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Envelope"
                  - properties:
                      data:
                        $ref: "#/components/schemas/KhassidaEdition"
        "404":
          description: Unknown number, or that edition does not cover this khassida
  /v1/edition/{edition}.json:
    get:
      tags: [khassida]
      summary: The whole corpus in one edition
      description: A bulk download, intended for building an offline copy in one request.
      operationId: getEditionBundle
      parameters:
        - $ref: "#/components/parameters/edition"
      responses:
        "200":
          description: Every khassida that edition covers
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Envelope"
                  - properties:
                      data:
                        type: object
                        properties:
                          edition:
                            $ref: "#/components/schemas/Edition"
                          khassidas:
                            type: array
                            items:
                              $ref: "#/components/schemas/KhassidaEdition"
        "404":
          description: Unknown edition
components:
  parameters:
    number:
      name: number
      in: path
      required: true
      description: Khassida number, 1 to 193.
      schema:
        type: integer
        minimum: 1
      example: 9
    edition:
      name: edition
      in: path
      required: true
      description: An edition identifier from /v1/editions.json.
      schema:
        type: string
      example: fr.karamati
  schemas:
    Envelope:
      type: object
      required: [code, status, data]
      properties:
        code:
          type: integer
          const: 200
        status:
          type: string
          const: OK
        data: {}
    Edition:
      type: object
      required: [identifier, language, name, type, format, direction, unit]
      properties:
        identifier: { type: string, example: fr.karamati }
        language: { type: string, example: fr }
        name: { type: string }
        englishName: { type: string }
        type: { type: string, enum: [original, transliteration, translation] }
        format: { type: string, enum: [text] }
        direction: { type: string, enum: [ltr, rtl] }
        unit:
          type: string
          enum: [verse, bayt]
          description: verse = one text per hemistich; bayt = one text per full line.
        source: { type: string, format: uri }
    KhassidaSummary:
      type: object
      required: [number, name, transliterationName, numberOfVerses, numberOfBayts, editions]
      properties:
        number: { type: integer, example: 9 }
        name: { type: string }
        transliterationName: { type: string }
        meter: { type: [string, "null"] }
        numberOfVerses: { type: integer }
        numberOfBayts: { type: integer }
        editions:
          type: array
          description: Identifiers of the editions that cover this khassida.
          items: { type: string }
    Verse:
      type: object
      required: [number, text]
      properties:
        number: { type: integer }
        text: { type: string, description: Arabic text of the hemistich. }
        transcription: { type: string }
        translations:
          type: object
          description: Keyed by verse-unit edition identifier.
          additionalProperties: { type: string }
    Bayt:
      type: object
      required: [number, verseFrom, verseTo, text]
      properties:
        number: { type: integer }
        verseFrom: { type: integer }
        verseTo: { type: integer }
        appNumber:
          type: integer
          description: Continuous numbering across khassida split into parts.
        text: { type: string, description: Arabic text of the full line. }
        translations:
          type: object
          description: Keyed by bayt-unit edition identifier.
          additionalProperties: { type: string }
    KhassidaFull:
      allOf:
        - $ref: "#/components/schemas/KhassidaSummary"
        - type: object
          required: [verses, bayts]
          properties:
            verses:
              type: array
              items: { $ref: "#/components/schemas/Verse" }
            bayts:
              type: array
              items: { $ref: "#/components/schemas/Bayt" }
    KhassidaEdition:
      type: object
      required: [number, name, transliterationName, numberOfVerses, numberOfBayts, edition, unit]
      properties:
        number: { type: integer }
        name: { type: string }
        transliterationName: { type: string }
        meter: { type: [string, "null"] }
        numberOfVerses: { type: integer }
        numberOfBayts: { type: integer }
        edition: { $ref: "#/components/schemas/Edition" }
        unit: { type: string, enum: [verse, bayt] }
        verses:
          type: array
          description: Present when unit is verse. Each row carries only this edition's text.
          items:
            type: object
            required: [number, text]
            properties:
              number: { type: integer }
              text: { type: string }
        bayts:
          type: array
          description: Present when unit is bayt.
          items:
            type: object
            required: [number, text, verseFrom, verseTo]
            properties:
              number: { type: integer }
              text: { type: string }
              verseFrom: { type: integer }
              verseTo: { type: integer }
              appNumber: { type: integer }
    Meta:
      type: object
      properties:
        apiVersion: { type: string, example: v1 }
        datasetVersion: { type: string, example: 1.0.0 }
        sourceChecksum:
          type: string
          description: SHA-256 of the source data; changes when any text changes.
        license: { type: string, example: MIT }
        originalWork:
          type: object
          properties:
            author: { type: string }
            status: { type: string, example: public domain }
        counts:
          type: object
          properties:
            khassidas: { type: integer }
            verses: { type: integer }
            bayts: { type: integer }
            editions: { type: integer }
        coverage:
          type: object
          description: Khassida count per edition identifier.
          additionalProperties: { type: integer }
        endpoints:
          type: array
          items: { type: string }
