OpenAPI.yml

openapi: 3.0.3
info:
  title: WhatTime App
  description: Core API for WhatTime Application
  version: '1.0'

servers:
  - url: 'http://localhost:8080/api/v1'
    description: Local dev
  - url: 'http://whattime.ru/api/v1'
    description: Production

paths:
  /login:
    post:
      description: Identificate by name
      operationId: login
      tags:
        - auth
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/User"
      responses:
        '204':
          description: No content
          headers:
            Set-Cookie:
              description: >
                JSON auth token encoded in Base64 
                with current user's id and name
              schema:
                type: string
                example: >
                  AuthToken=eyJpZCI6MSwibmFtZSI6IlZhc3lhIn0==; 
                  Path=/; HttpOnly; Max-Age=100500
        default:
          $ref: '#/components/responses/ErrorResponse'


  /currentUser:
    get:
      description: Get current user
      operationId: getCurrentUser
      tags:
        - auth
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Current user has been identified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '403':
          description: Current user has not been identified
        default:
          $ref: '#/components/responses/ErrorResponse'


  /logout:
    get:
      description: Logout current user
      operationId: logout
      tags:
        - auth
      responses:
        '204':
          description: User has been succesfully logged out
          headers:
            Set-Cookie:
              description: Auth token cookie with age equals to 0
              schema:
                type: string
        default:
          $ref: '#/components/responses/ErrorResponse'

  /events:
    post:
      description: Create new event
      operationId: createEvent
      tags:
        - events
      security:
        - cookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '201':
          description: The event has been created succesfully
          headers:
            Location:
              description: URL of the created event
              schema:
                type: string
                example: http://localhost:8080/events/1
        '403':
          description: Unidentified user can not create events
        default:
          $ref: '#/components/responses/ErrorResponse'

  /events/{eventId}:
    get:
      description: Get event by id
      operationId: getEventById
      tags:
        -  events
      parameters:
        - $ref: '#/components/parameters/eventId'
      responses:
        '200':
          description: The event has been found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        default:
          $ref: '#/components/responses/ErrorResponse'

  /events/{eventId}/intervals:
    post:
      description: Post intervals to event
      operationId: postIntervals
      tags:
        - events
      security:
        - cookieAuth: []
      parameters:
        - $ref: '#/components/parameters/eventId'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Interval'
      responses:
        '204':
          description: Intervals have beed posted succesfully
        '403':
          description: Unidentified user can not post intervals to events
        default:
          $ref: '#/components/responses/ErrorResponse'
    get:
      description: Get intervals by event id
      operationId: getIntervals
      tags:
        - events
      parameters:
        - $ref: '#/components/parameters/eventId'
      responses:
        '200':
          description: Intervals of the event have been found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Interval'
        default:
          $ref: '#/components/responses/ErrorResponse'

  /events/{eventId}/participants:
    get:
      description: Get users who voted
      operationId: getParticipants
      tags:
        - events
      parameters:
        - $ref: '#/components/parameters/eventId'
      responses:
        '200':
          description: The event has been found and the users returned
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        default:
          $ref: '#/components/responses/ErrorResponse'

  /events/{eventId}/result:
    get:
      description: Get result of the voting
      operationId: getVotingResult
      tags:
        - events
      parameters:
        - $ref: '#/components/parameters/eventId'
      responses:
        '200':
          description: The event has been found and the voting result returned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VotingResult"
        default:
          $ref: '#/components/responses/ErrorResponse'

components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: authToken

  parameters:
    eventId:
      name: eventId
      in: path
      description: ID of an event
      required: true
      schema:
        type: string

  responses:
    ErrorResponse:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Error:
      description: Error info
      type: object
      properties:
        timestamp:
          description: Error timestamp with timezone (RFC 3339)
          type: string
          format: date-time
          example: '2022-06-17T10:55:19+00:00'
        status:
          description: HTTP response status code
          type: integer
          example: 404
        error:
          description: HTTP status error message
          type: string
          example: 'Not Found'
        message:
          description: Error message
          type: string
          example: 'User has not been found'
        path:
          description: The failed request's path
          type: string
          example: '/notFoundPage'
      required:
        - timestamp
        - status
        - path

    User:
      description: User info
      type: object
      properties:
        name:
          description: The user's name
          type: string
          example: John
        id:
          description: The user's id
          type: string
          example: 1
          readOnly: true
      required:
        - name
        - id

    VotingResult:
      description: The result of users' voting at the event
      type: object
      properties:
        event:
          $ref: '#/components/schemas/Event'
        intervals:
          type: array
          items:
            $ref: '#/components/schemas/ResultInterval'
      required:
        - event
        - intervals
        - users

    Event:
      description: Event info
      type: object
      properties:
        id:
          description: UUID of the event
          type: string
          example: '12da28ba-88b5-4390-992b-5b1e066c07d3'
          readOnly: true
        title:
          description: Title of the event
          type: string
          example: John's birthday
        description:
          description: Short description of the event
          type: string
          example: Bring your own booze.
        owner:
          allOf:
            - $ref: '#/components/schemas/User'
            - readOnly: true
        createdAt:
          description: Time of creation of the event in seconds since the EPOCH
          type: integer
          example: 1655465889
          readOnly: true
      required:
        - id
        - title
        - owner
        - createdAt

    Interval:
      description: Interval of time info
      type: object
      properties:
        id:
          description: Global ID of the interval
          type: integer
          example: 7
        startTime:
          description: Start time of the interval in seconds since the EPOCH
          type: integer
          example: 1655465889
        endTime:
          description: End time of the interval in seconds since the EPOCH
          type: integer
          example: 1655466889
        owner:
          allOf:
            - $ref: '#/components/schemas/User'
            - readOnly: true
      required:
        - startTime
        - endTime
    ResultInterval:
      description: Combined users interval
      type: object
      properties:
        startTime:
          description: Start time of the interval in seconds since the EPOCH
          type: integer
          example: 1655465889
        endTime:
          description: End time of the interval in seconds since the EPOCH
          type: integer
          example: 1655466889
        owners:
          type: array
          items:
            $ref: '#/components/schemas/User'
      required:
        - startTime
        - endTime