Merge pull request #7 from e-gov/Otspunktide-täpsustamine

Otspunktide täpsustamine

3_Valijate_nimekiri/SPEC.md

@@ -9,6 +9,8 @@ algnimekirja ja valijate nimekirja muudatusi ehk muudatusnimekirju.
 Spetsifikatsioon on avalik. Spetsifikatsioon ei käsitle VIS3 ega EHS
 konfidentsiaalset siseehitust ega liidese konfidentsiaalseid elemente.
 
+Käesolevat spetsifikatsiooni tuleb kasutada koos VIS3 EHS API OpenAPI spetsifikatsiooniga (asub käesolevas repos, failis `vis-ehs-api.yaml`).
+
 ## 2. Sõnumivahetus nimekirjade edastamiseks
 
 Valijate nimekirja põhjal tuvastab EHS, isiku hääleõiguse ja
@@ -330,19 +332,17 @@ Näide antud meetodi kasutamiseks golang keeles on leitav repositooriumis
 
 ## 5. Transpordiprotokoll
 
-VIS3-EHS masinliides koosneb kahest API otspunktist.
+VIS3-EHS käesolev masinliides koosneb kahest API otspunktist.
 
-1.  API otspunkt `api-election-get-voters-changeset` muudatusnimekirjade
-    laadimiseks
-2.  API otspunkt `api-election-list-changesets` ülevaate saamiseks avalikustatud
+1.  API otspunkt `ehs-voters-changeset` konkreetse muudatusnimekirja
+    laadimiseks VIS3-st
+2.  API otspunkt `ehs-list-election-changesets` ülevaate saamiseks avalikustatud
     nimekirjadest
 
-Otspunktide nimed on hetkel fiktiivsed.
-
 Transpordiprotokoll on HTTPS, kuna volitamata ligipääs nimekirjadele tuleb
 tõkestada kasutatakse mõlemapoolselt autenditud TLS ühendusi.
 
-### 5.1 `api-election-get-voters-changeset`
+### 5.1 `ehs-voters-changeset`
 
 HTTP meetod on GET. Päringu tegemisel tuleb kasutada kohustuslikke parameetreid
 `changeset` ja `election_identifier`, kus
@@ -365,7 +365,7 @@ Sellise vastuse korral on HTTP status 200.
 Juhul kui vastava järjekorranumbriga muudatusnimekirja veel ei eksisteeri
 antakse vastuses HTTP status 404.
 
-### 5.1 `api-election-list-changesets`
+### 5.1 `ehs-list-election-changesets`
 
 HTTP meetod on GET. Päringu tegemisel tuleb kasutada kohustuslikku parameetrit
 `election_identifier`:
@@ -376,6 +376,8 @@ Kui EHS teeb API otspunkti, siis juhul kui vastava identifikaatoriga valimine
 eksisteerib, vastab VIS3 `application/json` tüüpi baidijadaga, mis sisaldab
 endas JSON vormingus viiteid kõigile väljastatud muudatusnimekirjadele.
 
+MÄRKUS. Viidetes tarnitavad URL-id ei ole õiged ja seetõttu mittekasutatavad. EHS peab konkreetse muudatuste nimekirja poole pöördumise URL-i koostama vastavalt VIS3 EHS API OpenAPI vormingus spetsifikatsioonile (asub käesolevas repos, failis `vis3-ehs-api.yaml`). VIS3 edasisestes versioonides eemaldame viidetest URL-id. 20.07.2021.
+
 ``` {.sourceCode .html}
 {
   changesets: [

vis3-ehs-api.yaml

@@ -0,0 +1,200 @@
+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 aadressina samal serveril
+          type: string
+          example: /api/v1/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