openapi: 3.0.3
info:
  title: Andmejälgija kasutusteabe teenus
  description: Andmejälgija teenus, mille käest küsib eesti.ee andmekogus toimunud isikuandmete töötluse infot ehk kasutusteavet
  contact:
    email: help@ria.ee
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
  version: 2.0.0
tags:
- name: usage
  description: Andmejälgija kasutusteave
paths:
  /findUsage:
    get:
      tags:
      - usage
      summary: Kasutusteabe küsimine
      description: Andmejälgija kasutusteabe küsimine andmesubjektile kuvamiseks eesti.ee-s
      operationId: findUsage
      parameters:
      - name: X-Road-UserId
        in: header
        description: Päringu algataja isikukood peab olema lisatud X-Road päise sisse
        schema:
          type: string
          example: EE12345678901
          externalDocs:
            description: Täiendav informatsioon X-Road päiste kohta
            url: https://x-tee.ee/docs/live/xroad/pr-rest_x-road_message_protocol_for_rest.html
        required: true
      - name: user_code
        in: query
        description: Andmesubjekti isikukood, kelle kohta tuleks tagastada kasutusteavet. Võib erineda X-Road-UserId päise väärtusest, kui päring on käivitatud esindusõiguse abil.
        schema:
          type: string
          example: EE12345678901
        required: true
      - name: period_start
        in: query
        description: Tagastada andmetöötluse kirjeid alates näidatud ajast
        required: false
        example: '2021-01-31T10:20:30'
        schema:
          type: string
          format: date-time
      - name: period_end
        in: query
        description: Tagastada andmetöötluse kirjeid kuni näidatud ajani
        required: false
        example: '2021-01-31T10:20:30'
        schema:
          type: string
          format: date-time
      - name: offset
        in: query
        description: Jätta vahele näidatud arvu kirjed ja tagastada järgmised (analoogne SQL offset käitumisega).
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: limit
        in: query
        description: Tagastada maksimaalselt näidatud arv kasutusteabe kirjeid (vaikimisi tagastatakse maksimaalselt 1000 kirjet).
        required: false
        schema:
          type: integer
          format: int32
          default: 1000
      responses:
        '200':
          description: Edukas päring
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindUsageResponse'
        '400':
          description: Päringu sisu ei vasta nõuetele
        '500':
          description: Päringu täitmisel tekkis viga
  /usagePeriod:
    get:
      tags:
      - usage
      summary: Kasutusteabe ajaperiood
      description: Ajaperiood, mille kohta saab pärida kasutusteavet
      operationId: usagePeriod
      responses:
        '200':
          description: Edukas päring
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsagePeriodResponse'
        '400':
          description: Päringu sisu ei vasta nõuetele
        '500':
          description: Päringu täitmisel tekkis viga
  /heartbeat:
    get:
      tags:
      - usage
      summary: Kasutusteabe elutukse
      description: Andmejälgija kasutusteabe elutukse küsimine
      operationId: heartbeat
      responses:
        '200':
          description: Edukas päring
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatResponse'
        '400':
          description: Päringu sisu ei vasta nõuetele
        '500':
          description: Päringu täitmisel tekkis viga
components:
  schemas:
    FindUsageResponse:
      type: object
      properties:
        totalUsages:
          description: Kirjete koguarv (tagastatud kirjete arv saab olla kirjete koguarvust väiksem, koguarv ei ole mõjutatud limit ja offset väärtustega)
          type: integer
          format: int32
          example: 1000
        usages:
          type: array
          items:
            $ref: '#/components/schemas/Usage'
    Usage:
      type: object
      required:
      - logtime
      - action
      - receiverCode
      - receiverSystem
      properties:
        logtime:
          description: Andmetöötluse ajamoment
          type: string
          format: date-time
          example: '2021-01-31T10:20:30'
        action:
          description: Menetluse/tegevuse/sündmuse inimmõistetav nimi, mis seletab andmetöötluse põhjust
          type: string
          example: Isiku ees- ja perenime päring
        receiverCode:
          description: Asutuse registrikood, kellele isikuandmeid edastati või kes isikuandmeid töötles
          type: string
          example: '12345678'
        receiverName:
          description: Asutuse nimi, kellele isikuandmeid edastati või kes isikuandmeid töötles
          type: string
          example: TEHIK
        receiverSystem:
          description: Infosüsteemi nimi, kellele isikuandmeid edastati või kes isikuandmeid töötles
          type: string
          example: Terviseportaal
    UsagePeriodResponse:
      type: object
      properties:
        period_start:
          description: Süsteem hoiab andmetöötluse kirjeid alates näidatud ajast
          type: string
          format: date-time
          example: '2021-01-31T10:20:30'
        period_end:
          description: Süsteem hoiab andmetöötluse kirjeid kuni näidatud ajani
          type: string
          format: date-time
          example: '2021-01-31T10:20:30'
    HeartbeatResponse:
      type: object
      properties:
        status:
          description: Elutuukse staatus
          type: string
          example: OK
          enum:
          - OK
          - FAIL
        message:
          description: Inimloetav elutuukse staatuse kirjeldav sõnum
          type: string
          example: API is ready
