openapi: '3.0.3'
info:
  title: 'IWG endpoints - Mediators API'
  description: |
    Offers public API endpoints that can be used to obtain mediators from Justizonline.
  version: '1.0'
  termsOfService: https://justizonline.gv.at/jop/web/iwg/terms
  contact:
    name: Bundesministerium für Justiz
    url: https://justizonline.gv.at
    email: justizonline-iwg@brz.gv.at

servers:
  - url: https://justizonline.gv.at/jop/api/
    description: Production Server

paths:
  /v1/qualified-persons/me:
    get:
      tags:
        - qualified-persons-mediators
      description: "Get a list of (possibly filtered if params used) mediators."
      operationId: listMeQualifiedPersonsV1
      parameters:
        - $ref: '#/components/parameters/QualifiedPersonsFilterFromParam'
        - $ref: '#/components/parameters/QualifiedPersonsFilterUntilParam'
      responses:
        '200':
          description: 'List of mediators'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeQualifiedPersons'

  /v1/qualified-persons/me/{addressCode}:
    get:
      tags:
        - qualified-persons-mediators
      description: "Get a specific mediator by the qualified person's `addressCode` (i.e. ID)"
      operationId: getMeQualifiedPersonByAddressCodeV1
      parameters:
        - $ref: '#/components/parameters/MeAddressCodePathParam'
      responses:
        '200':
          description: 'The specific mediator corresponding to the given path parameter `addressCode` (acting as the ID)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeQualifiedPerson'

components:
  schemas:
    FederalStates:
      type: string
      description: |
        Enum values:

        - A = complete federal area
        - 0 = Wien
        - 1 = Niederoesterreich
        - 2 = Burgenland
        - 3 = Oberoesterreich
        - 4 = Salzburg
        - 5 = Steiermark
        - 6 = Kaernten
        - 7 = Tirol
        - 8 = Vorarlberg
      enum:
        - A
        - 0
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
        - 7
        - 8
        -
    MeQualifiedPerson:
      type: object
      description: 'A single mediator object'
      properties:
        addressCode:
          type: string
          description: 'The so-called `address code` of the qualified person which uniquely identifies this particular mediator'
          readOnly: true
          pattern: '0[0-9]{6}'
        displayName:
          type: string
          description: >
            A (possibly) full name of the current qualified persons which may contains the first, middle
            and last name,(if any) academic titles (BSc, MSc, etc).
          example: 'Mag. Daniel Bailey, BSc'
        firstName:
          minLength: 2
          type: string
          description: "First name of the qualified person"
          example: "Max"
        lastName:
          minLength: 2
          type: string
          description: "Last name of the qualified person"
          example: "Mustermann"
        nameAffix:
          type: string
          description: "Name supplement"
        academicTitlePreceding:
          type: string
          description: "The academic title(s) that is/are written in front of the name"
          example: "Dr"
        academicTitleAfter:
          type: string
          description: "The academic title(s) that is/are written after the name"
          example: "MSc"
        job:
          type: string
          description: "The job/occupation of the mediator qualified person (DE: 'Beruf')"
          example: "lawyer (DE: 'Rechtsanwalt')"
        homepage:
          type: string
          description: "The homepage of the mediator."
          example: "https://www.mediator-austria.at"
        contacts:
          type: array
          description: "The adresses to this mediator."
          items:
            $ref: '#/components/schemas/ContactInfos'
          minItems: 1
          maxItems: 3
        scopesOfActivities:
          type: array
          description: "Activities in which the mediator has work to offer."
          items:
            type: string
        languages:
          type: array
          description: "Languages the mediator can offer."
          items:
            type: string
        listingFrom:
          type: string
          format: date
        listingTo:
          type: string
          format: date

    ContactInfos:
      type: object
      required:
        - postalCode
        - city
        - primaryPhoneNumber
        - email
      properties:
        address:
          type: string
          description: 'Full address consisting of street name, house number, staircase number and door number'
          example: 'Sakura street 7/2/12'
        postalCode:
          type: string
          description: 'Postal code'
          example: 1030
        city:
          type: string
          description: "Name of the city (DE: 'Ort')"
          example: 'Wien'
        primaryPhoneNumber:
          type: string
          description: 'Primary telephone number'
          maxLength: 40
          example: '+436763331289'
        secondaryPhoneNumber:
          type: string
          description: 'Secondary telephone number'
          maxLength: 40
          example: '+436763331289'
        fax:
          type: string
          description: 'Fax'
          maxLength: 40
          example: '+436763331289'
        email:
          type: string
          description: 'E-Mail address'
          maxLength: 250
          pattern: '^(?:[a-zA-Z0-9!#$%&''*+/=?^_{|}~-]+(?:\.[a-zA-Z0-9!#$%&''*+/=?^_{|}~-]+)*)@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?)$'
          example: 'something@fakemail.com'
        additionalInfo:
          type: string
          description: 'Additional information'
    MeQualifiedPersons:
      description: 'List of mediators'
      type: array
      items:
        $ref: '#/components/schemas/MeQualifiedPerson'

  parameters:
    QualifiedPersonsFilterFromParam:
      name: from
      in: query
      description: Filter param used to include mediators that have last been changed since the `from` date
      example: 2023-01-31
      required: false
      style: form
      explode: true
      schema:
        type: string
        format: date
    QualifiedPersonsFilterUntilParam:
      name: until
      in: query
      description: Filter param used to include mediators that have been changed up to the `until` date
      example: 2023-01-31
      required: false
      style: form
      explode: true
      schema:
        type: string
        format: date
    MeAddressCodePathParam:
      name: addressCode
      in: path
      description: "The mediators unique address code (which acts as the ID)"
      required: true
      style: simple
      explode: false
      schema:
        type: string
        pattern: '0[0-9]{6}'

  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-Api-Key
      description: "For the purpose of authorization, the API key must be sent with the call"

security:
  - api_key: [ ]