vis3-ehs-api.yaml

openapi: 3.0.1
info:
  title: VIS3 EHS API spetsifikatsioon
  description: VIS3 pakub e-hääletamise süsteemile (EHS) API-d, millega EHS saab VIS3-st laadida valijate nimekirja muudatusi ja VIS3-e saata e-hääletanute koguarvu teatist. Spetsifikatsioon on avalik (avaldatakse GitHub-is, repos https://github.com/e-gov/VIS3-EHS.
  termsOfService: http://swagger.io/terms/
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://vis-ehs-api.ria.ee
    description: PROD
  - url: https://vis-ehs-api-test.ria.ee
    description: TEST
  - url: https://vis-ehs-api-dev.ria.ee
    description: DEV

paths:

  /online-voters:
    post:
      summary: e-hääletanute koguarvu teatise edastamine
      requestBody:
        description: e-hääletanute koguarvu teatise päringu keha
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OnlineVotersTotal"
      responses:
        204:
          $ref: "#/components/responses/204"
        400:
          $ref: "#/components/responses/400"
        403:
          $ref: "#/components/responses/403"
        500:
          $ref: "#/components/responses/500"

  /ehs-election-voters-changeset:
    get:
      summary: Valijate nimekirja muudatused EHS-ile
      parameters:
        - name: electionCode
          in: query
          description: Valimissündmuse tunnus
          required: true
          schema:
            type: string
          example: RH_2021
        - name: changeset
          in: query
          description: Valijate muudatusnimekirja järjenumber (1, 2, 3, ...)
          required: true
          schema:
            type: integer
      responses:
        200:
          description: Valijate nimekirja muudatuskirjed
          content:
            application/octet-stream:
              schema:
                description:
                  Jaoskonnas hääletanute üldstatistika
                type: string
                format: binary
        400:
          $ref: "#/components/responses/400"
        403:
          $ref: "#/components/responses/403"
        500:
          $ref: "#/components/responses/500"

  /ehs-list-election-changesets:
    get:
      summary: Valijate olemasolevate muudatuste nimekirjade loetelu EHS-ile
      parameters:
        - name: electionCode
          in: query
          description: Valimissündmuse tunnus
          required: true
          schema:
            type: string
          example: RH_2021
      responses:
        200:
          description: Nimekiri muudatusnimekirjadest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VotersChangesets'
        400:
          $ref: "#/components/responses/400"
        403:
          $ref: "#/components/responses/403"
        500:
          $ref: "#/components/responses/500"

components:
  schemas:

    OnlineVotersTotal:
      type: object
      description: e-hääletanute koguarvu teatis
      required:
        - TOTAL
      properties:
        TOTAL:
          type: object
          required:
            - time
            - election
            - online-voters
          properties:
            time:
              description: Ajahetk e-hääletanute koguarvu "online-voters" väärtuse jaoks
              type: string
              format: date-time
              example: "2020-10-16T09:32:21Z"
            election:
              description: Valimissündmuse tunnus
              type: string
              example: KOV_2021
            online-voters:
              description: e-hääletanute koguarv ajahetkel "time". Peab olema naturaalarv (0, 1, 2, ...)!
              type: integer
              format: int32

    VotersChangesets:
      type: object
      description: Nimekiri olemasolevatest muudatusnimekirjadest
      required:
        - changesets
      properties:
        changesets:
          type: array
          description: Nimekiri muudatusnimekirjade ressursidest
          items:
            $ref: "#/components/schemas/VotersChangeset"

    VotersChangeset:
      type: object
      description: Muudatusnimekirja ressursi detailid
      required:
        - changeset
        - url
        - from
        - to
      properties:
        changeset:
          description: Muudatusnimekirja järjenumber
          type: integer

        url:
          description: Ressursi asukoht URL-i tee ja päringu osadena (path and query parts of the URL) samal serveril
          type: string
          example: /ehs-election-voters-changeset?electionCode=RH_2021&changeset=1

        from:
          description: Muudatusnimekirja ajavahemiku alguse aeg
          type: string
          format: date-time

        to:
          description: Muudatusnimekirja ajavahemiku lõpu aeg
          type: string
          format: date-time

    Error:
      type: object
      description: Veasõnum
      properties:
        field:
          type: string
          description: Vea põhjustanud andmeväli
          example: "changeset"
        value:
          type: object
          description: Vea põhjustanud andmevälja väärtus
          example: "1"

  responses:
    204:
      description: Toiming õnnestus

    400:
      description: Vigane päring
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    403:
      description: Õigused päringu teostamiseks puuduvad
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    500:
      description: Süsteemi tehniline viga. Toiming ebaõnnestus