dotdotvote/api-description.yml

---
swagger: "2.0"
info:
  description: |
    Dot dot vote!    
  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"
host: "localhost:8000"
basePath: "/api/v1"
tags:
- name: "poll"
  description: Poll manipulation APIs
  externalDocs:
    description: "Find out more"
    url: "http://swagger.io"
schemes:
- "http"
- "https"
paths:
  /polls:
    put:
      tags:
      - "poll"
      summary: "Create a new poll"
      description: "Create a new poll"
      operationId: "createPoll"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: |
          Insertable Poll object that must be provided in order to actually create the poll.          
        required: true
        schema:
          $ref: "#/definitions/InsertablePoll"
      responses:
        '201':
          description: |
            Poll created successfully            
          schema:
            type: 'object'
            properties:
              poll:
                type: string
                description: 'A UUID for the generated poll'
                example: '8497479a-9f07-4530-9a5c-2824238d5975'
        "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
        type: string
        format: uuid

      responses:
        200:
          description: Poll found
          schema:
            $ref: '#/definitions/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
        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
        type: string
        format: uuid
      responses:
        200:
          description: Poll found
          schema:
            $ref: '#/definitions/PollResults'
        400:
          description: |
            Either the UUID parameter wasn't provided or it did not parse as a legitimate UUIDv4            
        404:
          description: |
            Poll not found            
definitions:
  PollResponse:
    type: object
    properties:
      poll:
        $ref: '#/definitions/RawPoll'
      choices:
        type: array
        items:
          $ref: '#/definitions/RawChoice'
  PollResults:
    type: object
    properties:
      poll:
        $ref: '#/definitions/RawPoll'
      choices:
        type: array
        items:
          $ref: '#/definitions/RawChoice'
      votes:
        type: array
        items:
          $ref: '#/definitions/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'