qv/cmd/web/openapi.yml

openapi: 3.0.3
info:
  title: qv - dlmw
  description: |-
    This is the documentation for the qv (Quadratic Voting) API.
  termsOfService:
  contact:
    email: dylan@dlmw.ch
  license:
    name: GNU General Public License Version 3
    url: https://www.gnu.org/licenses/gpl-3.0.txt
  version: 0.0.1
externalDocs:
  description: Get the code
  url: https://code.dlmw.ch/dlmw/qv
servers:
  - url: https://qv.dlmw.ch/api
tags:
  - name: election
    description: Retrieve data related to elections
  - name: vote
    description: Retrieve data related to votes

paths:
  /election/{id}:
    get:
      tags:
        - election
      summary: Get an election
      operationId: getElection
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the election
          schema:
            type: string
      responses:
        200:
          description: Election returned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Election"
        400:
          description: Request malformed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        404:
          description: Election not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /election:
    post:
      tags:
        - election
      summary: Create a new election
      operationId: createElection
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateElectionRequest"
      responses:
        200:
          description: Election created. Body only returned if voterAreKnown is true
          headers:
            Location:
              schema:
                type: string
              description: The path to the newly created election
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateElectionResponse"
        422:
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /election/{id}/votes:
    post:
      tags:
        - vote
      summary: Cast your votes for an election
      operationId: createVotes
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the election
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateVotesRequest"
      responses:
        201:
          description: Votes cast
        400:
          description: Request malformed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        404:
          description: Election not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        422:
          description: Unprocessable content
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /election/{id}/results:
    get:
      tags:
        - election
      summary: Get the results of an election
      operationId: getElectionResults
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the election
          schema:
            type: string
      responses:
        200:
          description: Election results returned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ElectionResultsResponse"
        400:
          description: Request malformed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        404:
          description: Election doesn't exist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        500:
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  schemas:
    Election:
      type: object
      required:
        - id
        - name
        - tokens
        - areVotersKnown
        - maxVoters
        - createdAt
        - expiresAt
        - choices
      properties:
        id:
          type: string
        name:
          type: string
        tokens:
          type: integer
        areVotersKnown:
          type: boolean
        maxVoters:
          type: integer
        createdAt:
          type: string
        expiresAt:
          type: string
        choices:
          type: array
          items:
            type: string

    CreateElectionRequest:
      type: object
      required:
        - name
        - tokens
        - areVotersKnown
        - maxVoters
        - expiresAt
        - choices
      properties:
        name:
          type: string
          minLength: 1
        tokens:
          type: integer
          minimum: 1
        areVotersKnown:
          type: boolean
        maxVoters:
          type: integer
          minimum: 0
          description: Must be greater than 0 when voters are known; 0 = no limit
        expiresAt:
          type: string
          format: date-time
        choices:
          type: array
          items:
            type: string
            minLength: 1
          minItems: 1
          uniqueItems: true

    CreateElectionResponse:
      type: object
      properties:
        voterIdentities:
          type: array
          items:
            type: string
            minLength: 1
          uniqueItems: true

    CreateVotesRequest:
      type: object
      required:
        - choices
      properties:
        voterIdentity:
          type: string
          description: Must be filled if election has known voters
        choices:
          type: array
          items:
            required:
              - choiceText
              - tokens
            properties:
              choiceText:
                type: string
                minLength: 1
              tokens:
                type: integer

    ElectionResultsResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/VotesForChoice"

    VotesForChoice:
      type: object
      required:
        - choice
        - votes
      properties:
        choice:
          type: string
        votes:
          type: integer

    ErrorResponse:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
          description: Human-readable error message
        code:
          type: integer
          description: Machine-readable error code
        details:
          type: object
          description: Additional error details when available