API.yml

openapi: 3.0.0
info:
  description: Authentication is mainly handled through a small token in the headers. The server validates and authorizes on a per request basis.
  version: "1.0.0"
  title: Amity API
servers:
  - url: "http://127.0.0.1:3001/api/"
    description: localhost
  - url: "http://salt.styl.services/api/"
    description: prod
paths:
  /meetings:
    post:
      summary: Add a blind meeting to the schedule
      description: 'if the same user has a meeting at the same time. if yes, return that.
      if theres a meeting at that time with only one participantm. if yes. add posting user and return
      else create a new with only poster as participant and return that'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                time:
                  $ref: "#/components/schemas/UnixEpoch"

      responses:
        "200":
          description: response may not include 2 participants
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Meeting"

    get:
      summary: list all metting in which you are attending
      security:
        - x-access-token: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                properties:
                  meetings:
                    type: array
                    items:
                      $ref: "#/components/schemas/Meeting"
  /register:
    post:
      summary: register new user
      description: check if the email is registered. If not, register the email
      requestBody:
        description: all thats needed for a new user
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegistrationObj"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: Email already registered
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: DuplicateEmailError
                user-reason: email is already registered.
  /logout:
    get:
      summary: clear x-access-token cookie
      responses:
        "200":
          description: clearing client cookie
  /login:
    post:
      summary: authenticate user by email and hash
      requestBody:
        description: users password and hash
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthCredentials"
      responses:
        "200":
          description: auth successful
          headers:
            Set-Cookie:
              description: access-token
              schema:
                type: string
                pattern: ^[^\W]+.[^\W]+.[^\W]+$
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        401:
          description: auth failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      summary: "get user info associated with the requests 'x-access-token'"
      security:
        - x-access-token: []
      responses:
        "200":
          description: token is valid. response contains associated user info.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        401:
          description: "no valid token found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /settings:
    put:
      summary: update user settings by passing settings object
      security:
        - x-access-token: []
      requestBody:
        description: complete settings object with new info.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Settings"
      responses:
        "200":
          description: settings object valid. returning settings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Settings"
        "400":
          description: settings object invalid
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: ValidationError
                user-reason: error saving new settings
security:
  - key: []
components:
  schemas:
    Meeting:
      description: represents a scheduled meeting
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: "#/components/schemas/UUID"
        time:
          $ref: "#/components/schemas/UnixEpoch"
        users:
          type: array
          items:
            $ref: "#/components/schemas/UUID"
          minItems: 2
          uniqueItems: true
          example:
            - a1a07302-3fac-443b-ab6c-d90327cdf784
            - 3353efd3-a5e5-40e5-aa5a-91eca1979221
    MeetingRequest:
      description: represents a scheduled meeting
      type: object
      additionalProperties: false
      properties:
        time:
          $ref: "#/components/schemas/UnixEpoch"
        users:
          type: array
          items:
            $ref: "#/components/schemas/UUID"
          minItems: 2
          uniqueItems: true
          example:
            - a1a07302-3fac-443b-ab6c-d90327cdf784
            - 3353efd3-a5e5-40e5-aa5a-91eca1979221
    RegistrationObj:
      type: object
      additionalProperties: false
      properties:
        username:
          $ref: "#/components/schemas/Username"
        email:
          $ref: "#/components/schemas/Email"
        password:
          $ref: "#/components/schemas/PasswordHash"
    User:
      description: describes user incl. settings
      type: object
      additionalProperties: false
      properties:
        userId:
          $ref: "#/components/schemas/UUID"
        username:
          $ref: "#/components/schemas/Username"
        email:
          $ref: "#/components/schemas/Email"
        bio:
          type: string
          maxLength: 2500
          example: skatebording nucleor physicist wiot a degree in spelling misstakes

        tagline:
          type: string
          maxLength: 100
          example: first man on the baloon

        avatar:
          type: string
          format: URI
          minItems: 10
          maxLength: 100
          pattern: ^http.?\/\/\S+\.\S+$
          example: https://url.domain.com/image.jpg

        settings:
          $ref: "#/components/schemas/Settings"
        updated:
          $ref: "#/components/schemas/UnixEpoch"
    Settings:
      type: object
      properties:
        profileVisible:
          type: boolean
          description: indicates wether the user can be seen by other users
          example: true
    Error:
      description: general error
      type: object
      properties:
        error:
          type: string
          format: ErrorType
          maxLength: 30
        user-reason:
          type: string
          maxLength: 100
          format: user-friendly
    AuthCredentials:
      description: login request object
      type: object
      additionalProperties: false
      properties:
        email:
          $ref: "#/components/schemas/Email"
        password:
          $ref: "#/components/schemas/PasswordHash"

    UUID:
      description: UUID v4. guaranteed (practically) unique identifier.
      type: string
      pattern: ^[0-9a-e]{8}-[0-9a-e]{4}-[0-9a-e]{4}-[0-9a-e]{4}-[0-9a-e]{12}$
      maxLength: 36
      minLength: 36
      example: a1a07302-3fac-443b-ab6c-d90327cdf784
    Email:
      description: users email all in lowercase
      type: string
      pattern: ^.+@.+\..+
      maxLength: 30
      format: email
      example: user@example.com
    Username:
      description: userselected display-name
      type: string
      example: Allan888
      maxLength: 30
      minLength: 1
      pattern: ^\S+$
    PasswordHash:
      description: sha512 hash of <email><password>
      type: string
      maxLength: 128
      minLength: 128
      pattern: ^[0-9a-f]+$
      format: SHA512
      example: 0a50261ebd1a390fed2bf326f2673c145582a6342d523204973d0219337f81616a8069b012587cf5635f6925f1b56c360230c19b273500ee013e030601bf2425
    UnixEpoch:
      type: number
      description: UNIX time w/ millis
      minimum: 1600000000000
      maximum: 2000000000000
      example: 1606727487134
  securitySchemes:
    key:
      type: apiKey
      name: x-api-key
      in: header
    x-access-token:
      type: apiKey
      name: x-access-token
      in: cookie