api-description.yml

---
openapi: "3.0.0"
info:
  description: |
    Dot dot vote! This OpenAPI definition may become inaccurate as the application
    evolves. Until such a point where this spec is used for automated acceptance
  version: "1.0.0"
  title: Dot dot vote
  contact:
    email: "rtyler+dotdotvote@brokenco.de"
  license:
    name: "LGPL v3.0"
    url: "https://www.gnu.org/licenses/lgpl-3.0.en.html"
servers:
  - url: 'https://www.dotdotvote.com/api/v1'
    description: Production/public environment
  - url: 'http://localhost:8000/api/v1'
    description: Local dev server (APIv1)

tags:
- name: "poll"
  description: Poll manipulation APIs
  externalDocs:
    description: "Find out more"
    url: "http://swagger.io"
paths:
  /polls:
    put:
      tags:
      - "poll"
      summary: "Create a new poll"
      description: "Create a new poll"
      operationId: "createPoll"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsertablePoll'
      responses:
        '201':
          description: |
            Poll created successfully
          content:
            application/json:
              schema:
                type: 'object'
                properties:
                  poll:
                    type: string
                    description: 'A UUID for the generated poll'
                    example: 'e2b75a74-0dd9-4324-bc7e-4b1aa720f2f1'
        "422":
          description: |
            Invalid JSON supplied
        '500':
          description: |
            Some server side error has occurred.
  '/polls/{uuid}':
    get:
      tags:
      - poll
      summary: 'Fetch the details of the given poll'
      description: |
        Access the Poll details and metadata, but _not_ the results
      parameters:
      - in: path
        name: uuid
        required: true
        description: 'The UUID for the generated poll'
        example: 'e2b75a74-0dd9-4324-bc7e-4b1aa720f2f1'
        schema:
          type: string
          format: uuid

      responses:
        200:
          description: Poll found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PollResponse'
        400:
          description: |
            Either the UUID parameter wasn't provided or it did not parse as a legitimate UUIDv4
        404:
          description: |
            Poll not found

  '/polls/{uuid}/vote':
    post:
      tags:
      - poll
      summary: 'Vote in the specified poll'
      parameters:
      - in: path
        name: uuid
        required: true
        description: 'The UUID for the generated poll'
        example: 'e2b75a74-0dd9-4324-bc7e-4b1aa720f2f1'
        schema:
          type: string
          format: uuid
      responses:
        200:
          description: Vote submitted
        400:
          description: |
            Either the UUID parameter wasn't provided or it did not parse as a legitimate UUIDv4
        404:
          description: |
            Poll not found

  '/polls/{uuid}/results':
    get:
      tags:
      - poll
      summary: 'Fetch the results for the specified poll'
      parameters:
      - in: path
        name: uuid
        required: true
        description: 'The UUID for the generated poll'
        example: 'e2b75a74-0dd9-4324-bc7e-4b1aa720f2f1'
        schema:
          type: string
          format: uuid
          example: '8497479a-9f07-4530-9a5c-2824238d5975'
      responses:
        200:
          description: Poll found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PollResults'
        400:
          description: |
            Either the UUID parameter wasn't provided or it did not parse as a legitimate UUIDv4
        404:
          description: |
            Poll not found
components:
  schemas:
    PollResponse:
      type: object
      properties:
        poll:
          $ref: '#/components/schemas/RawPoll'
        choices:
          type: array
          items:
            $ref: '#/components/schemas/RawChoice'
    PollResults:
      type: object
      properties:
        poll:
          $ref: '#/components/schemas/RawPoll'
        choices:
          type: array
          items:
            $ref: '#/components/schemas/RawChoice'
        votes:
          type: array
          items:
            $ref: '#/components/schemas/RawVote'
    RawPoll:
      type: object
      properties:
        id:
          type: number
          format: int32
        uuid:
          type: string
          format: uuid
        title:
          type: string
        created_at:
          type: string
          format: date-time
    RawChoice:
      type: object
      properties:
        id:
          type: number
          format: int32
        poll_id:
          type: number
          format: int32
        details:
          type: string
        created_at:
          type: string
          format: date-time
    RawVote:
      type: object
      properties:
        id:
          type: number
          format: int32
        poll_id:
          type: number
          format: int32
        choice_id:
          type: number
          format: int32
        dots:
          type: number
          format: in32
        voter:
          type: string
        created_at:
          type: string
          format: date-time
    InsertablePoll:
      type: "object"
      properties:
        title:
          type: "string"
          example: 'My amazing poll!'
        choices:
          type: "array"
          items:
            type: "string"
            example: 'Choice 1'