openapi: 3.0.3
info:
  title: Trickregister API
  version: "1.0.0"
  description: Öffentliche Suche und Direktabruf von Trick-Nummern.
servers:
  - url: https://trickregister.de/api
paths:
  /api.php:
    get:
      summary: Suche oder Direktabruf
      description: |
        Suche mit `q` (Freitext) oder Direktabruf mit `code`.
        Wenn `only_code=1`, wird nur die Code-Nummer des besten Treffers zurückgegeben.
      parameters:
        - in: query
          name: q
          schema: { type: string }
          description: Freitext-Suche (UTF-8)
          example: Brille hochschieben statt Hand heben
        - in: query
          name: code
          schema: { type: string }
          description: Registernummer (z. B. 1.2.3.5)
          example: 1.2.3.5
        - in: query
          name: only_code
          schema:
            type: integer
            minimum: 0
            maximum: 1
            default: 0
          description: Nur die Code-Nummer des Top-Treffers ausgeben
          example: 1
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
          description: Anzahl Ergebnisse in `results`
          example: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CodeResponse'
                  - $ref: '#/components/schemas/SearchResponse'
              examples:
                search:
                  summary: Vollständige Suche
                  value:
                    query: Brille hochschieben statt Hand heben
                    best:
                      code: 7.3.2
                      title: Brille hochschieben statt Hand heben
                      score: 1
                      percent: 100
                    results:
                      - code: 7.3.2
                        title: Brille hochschieben statt Hand heben
                        score: 1
                        percent: 100
                      - code: 8.1.5
                        title: Blickkontakt statt Handzeichen
                        score: 0.73
                        percent: 68
                    took_ms: 7
                onlyCode:
                  summary: Nur Code
                  value:
                    code: 7.3.2
        '400':
          description: Missing query
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
              example: { "error": "missing_query" }
        '404':
          description: Not found (code)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
              example: { "error": "not_found" }
        '500':
          description: Internal error
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
              example: { "error": "internal" }
components:
  schemas:
    ResultItem:
      type: object
      properties:
        code: { type: string }
        title: { type: string }
        score: { type: number }
        percent: { type: integer }
      required: [code, title]
    SearchResponse:
      type: object
      properties:
        query: { type: string }
        best:
          oneOf:
            - $ref: '#/components/schemas/ResultItem'
            - type: "null"
        results:
          type: array
          items: { $ref: '#/components/schemas/ResultItem' }
        took_ms: { type: integer }
      required: [results]
    CodeResponse:
      type: object
      properties:
        code: { type: string }
        title:
          type: string
          description: Nur bei `?code=...`; fehlt bei `only_code=1`
      required: [code]
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          enum: [missing_query, not_found, internal]
