openapi.yml

openapi: 3.0.3
info:
  title: AHBesser API Documentation
  description: >
    This is the description for the API of the ahbesser web application.

    Some useful links:
    - [The machine-readable-anwendungshandbuecher repository](https://github.com/Hochfrequenz/machine-readable_anwendungshandbuecher)
    - [kohlr_AHB_i - the CLI tool to scrape the AHB tables from docx files](https://github.com/Hochfrequenz/kohlrahbi)
  termsOfService: http://swagger.io/terms/
  contact:
    email: kevin.krechan@hochfrequenz.de
  license:
    name: GPL-3.0
    url: https://www.gnu.org/licenses/gpl-3.0.en.html
  version: 0.0.1
externalDocs:
  description: JSON files of the AHB documents
  url: https://github.com/Hochfrequenz/machine-readable_anwendungshandbuecher
servers:
  - url: https://ahbesser.hochfrequenz.de/api/v1
tags:
  - name: ahb
    description: Everything about AHB documents
paths:
  /api/ahb/{format-version}/{pruefi}:
    get:
      tags:
        - ahb
      summary: Get an AHB document for a Pruefidentifikator from the provided Formatversion
      operationId: getAhb
      parameters:
        - name: format-version
          in: path
          description: Formatversion of the AHB to return
          required: true
          schema:
            $ref: '#/components/schemas/FormatVersion'
        - name: pruefi
          in: path
          description: Pruefidentifikator of the AHB to return
          required: true
          schema:
            type: string
            example: '25007'
        - name: format
          in: query
          description: Format of the AHB file to return
          required: false
          schema:
            type: string
            enum: [json, xlsx, csv]
            default: json
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ahb'
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
            text/csv:
              schema:
                type: string
                format: binary
      security:
        - ahbesser_auth:
            - read:ahb
  /api/format-versions:
    get:
      tags:
        - ahb
      summary: Get a list of all available format versions
      operationId: getFormatVersions
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example: [FV2310, FV2404, FV2410]
  /api/format-versions/{format-version}/pruefis:
    get:
      tags:
        - ahb
      summary: Get a list of all available Pruefidentifikators for a given format version
      operationId: getPruefis
      parameters:
        - name: format-version
          in: path
          description: Formatversion of the AHB to return
          required: true
          schema:
            $ref: '#/components/schemas/FormatVersion'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    pruefidentifikator:
                      type: string
                      pattern: '^\\d{5}$'
                      example: '31001'
                    name:
                      type: string
                      example: 'Pruefidentifikator Name'
  /version:
    get:
      tags:
        - maintenance
      summary: Get the current version of the AHBesser application
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'

components:
  schemas:
    Ahb:
      type: object
      properties:
        lines:
          type: array
          items:
            type: object
            properties:
              ahb_expression:
                type: string
                example: 'Must'
              conditions:
                type: string
              data_element:
                type: string
                example: '0062'
              guid:
                type: string
                format: uuid
                example: '123e4567-e89b-12d3-a456-426614174000'
              index:
                type: integer
                example: 1
              name:
                type: string
                example: 'Header Name'
              section_name:
                type: string
                example: 'Header Section'
              segment_code:
                type: string
                example: 'UNH'
              segment_group_key:
                type: string
                example: '001'
              value_pool_entry:
                type: string
                example: 'Entry1'
            required:
              - ahb_expression
              - data_element
              - guid
              - index
              - name
              - section_name
              - segment_code
              - segment_group_key
              - value_pool_entry
        meta:
          type: object
          properties:
            description:
              type: string
              example: 'API response meta description'
            direction:
              type: string
              example: 'inbound'
            pruefidentifikator:
              type: string
              example: '25007'
          required:
            - description
            - direction
            - pruefidentifikator
      required:
        - lines
        - meta
    FormatVersion:
      type: string
    Version:
      type: object
      properties:
        version:
          type: string
          example: '1.0.3'
        buildDate:
          type: string
          example: '2024-01-15'
        commitHash:
          type: string
          example: 'a1b2c3d4'
        commitDate:
          type: string
          example: '2024-01-14'
        buildBranch:
          type: string
          example: 'main'
  securitySchemes:
    ahbesser_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://petstore3.swagger.io/oauth/authorize
          scopes:
            read:ahb: read your ahb