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: http://swagger.io/terms/
  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: Find out more about qv # todo
  url: http://swagger.io # todo
servers:
  - url: https://petstore3.swagger.io/api/v3 # todo
tags:
  - name: election
    description: Retrieve data related to elections
  - name: vote
    description: Retrieve data related to votes

paths:
  /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: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateVotesRequest"
      responses:
        200:
          description: Votes cast
        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: integer
      responses:
        200:
          description: Election results returned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ElectionResultsResponse"
        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
        - expiresAt
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
        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
        createdAt:
          type: string
          format: date-time
          readOnly: true
        expiresAt:
          type: string
          format: date-time
        choices:
          type: array
          items:
            $ref: '#/components/schemas/Choice'
        voters:
          type: array
          items:
            $ref: '#/components/schemas/Voter'

    Choice:
      type: object
      required:
        - text
        - electionId
      properties:
        text:
          type: string
          minLength: 1
        electionId:
          type: integer
          format: int64

    Voter:
      type: object
      required:
        - identity
        - electionId
      properties:
        identity:
          type: string
          minLength: 1
          description: When voters are known, passcodes will be pre-generated
        electionId:
          type: integer
          format: int64
        votes:
          type: array
          items:
            $ref: '#/components/schemas/Vote'

    Vote:
      type: object
      required:
        - voterIdentity
        - electionId
      properties:
        voterIdentity:
          type: string
          minLength: 1
        electionId:
          type: integer
          format: int64
        choiceText:
          type: string
          nullable: true
        tokens:
          type: integer
          minimum: 1
          nullable: true
        calculatedVoteCount:
          type: integer
          readOnly: true
          description: Calculated as floor(sqrt(tokens))
        createdAt:
          type: string
          format: date-time
          readOnly: true

    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

    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
          nullable: true