api.yml

openapi: 3.0.3
info:
  title: "GMCServer Backend API"
  version: 0.1.0
  license:
    name: GNU Affero General Public License v3.0 or later
    url: https://www.gnu.org/licenses/agpl-3.0-standalone.html
  contact:
    name: vinceh121
    email: contact@vinceh121.me
    url: https://vinceh121.me
servers:
  - url: https://gmc.vinceh121.me/api/v1
paths:
  /auth/login:
    post:
      description: Perform a login
      parameters:
        - name: username
          in: query
          required: true
          example: "vinceh121"
          schema:
            type: string
        - name: password
          in: query
          required: true
          example: "12345"
          schema:
            type: string
      responses:
        '200':
          description: Successfully logged-in
          content:
            application/json:
              schema:
                parameters:
                  - name: token
                    type: string
                    description: Token to be passed in Authorization header
                  - name: id
                    type: string
                    description: User's ID
                  - name: mfa
                    type: boolean
  /auth/register:
    post:
      description: Create an account
      parameters:
        - name: username
          in: query
          required: true
          schema:
            type: string
        - name: password
          in: query
          required: true
          schema:
            type: string
        - name: email
          in: query
          required: true
          schema:
            type: string
        - name: captchaId
          in: query
          required: false
          schema:
            type: string
        - name: captchaAnswer
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successfully created account
          content:
            application/json:
              schema:
                parameters:
                  - name: token
                    type: string
                  - name: id
                    type: string
  /user/{userId}:
    get:
      description: Fetch a user
      parameters:
        - name: userId
          in: path
          required: true
          example: "5ed7d9b8de22630a0105e7bf"
          schema:
            type: string
      responses:
        '200':
          description: Successfully fetched a user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/user"
        '400':
          description: Format error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorResult"
        '404':
          description: No user by that ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorResult"
  /user/me:
    get:
      description: Fetch the currently logged in user
      responses:
        '200':
          description: Successfully fetched current user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/user"
        '404':
          description: User not logged in
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorResult"
    put:
      description: Update current user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#components/schemas/updateUser"
      responses:
        '200':
          description: Successfully updated user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorResult"
        '409':
          description: Username or email is already taken
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorResult"
        '403':
          description: When changing password, current password failed to validate
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorResult"
    delete:
      description: Delete current user
      requestBody:
        required: true
        content:
          application/json:
            schema:
             type: object
             properties:
               password:
                type: string
      responses:
        '200':
          description: Successfully deleted user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorResult"
        '400':
          description: Password field missing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorResult"
        '403':
          description: Password failed to validate
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorResult"
  /device:
    post:
      description: Create device
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/device"
      responses:
        '200':
          description: Successfully created device
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/device"
        '400':
          description: Format error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorResult"
        '403':
          description: Not authenticated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorResult"
        '406':
          description: Device limit reached
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorResult"
  /device/{deviceId}:
    get:
      description: Get a device by ID
      parameters:
        - name: deviceId
          in: path
          required: true
          example: "5ed7d9b8de22630a0105e7c0"
          schema:
            type: string
      responses:
        '200':
          description: Successfully fetched device
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/device"
        '404':
          description: No device by that ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorResult"
  /device/{deviceId}/timeline:
    get:
      description: Get a device's records timeline
      parameters:
        - name: deviceId
          in: path
          required: true
          example: "5ed7d9b8de22630a0105e7c0"
          schema:
            type: string
        - name: start
          in: query
          schema:
            type: integer
        - name: end
          in: query
          schema:
            type: integer
        - name: full
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Sucessfully fetched device timeline
          content:
            'application/json':
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/record"
  /device/{deviceId}/stats/{field}:
    get:
      description: Get statistical information for a specific field
      parameters:
        - name: deviceId
          in: path
          required: true
          example: "5ed7d9b8de22630a0105e7c0"
          schema:
            type: string
        - name: field
          in: path
          required: true
          example: "cpm"
          schema:
            type: string
        - name: start
          in: query
          schema:
            type: integer
        - name: end
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Successfully calculated stats
          content:
            'application/json':
              schema:
                $ref: "#/components/schemas/deviceStats"
        '204':
          description: No records withing constraints
          content:
            'application/json':
              schema:
                $ref: "#/components/schemas/errorResult"
  /map:
    get:
      description: Fetch a world map of devices
      parameters:
        - name: swlon
          in: query
          schema:
            type: number
        - name: swlat
          in: query
          schema:
            type: number
        - name: nelon
          in: query
          schema:
            type: number
        - name: nelat
          in: query
          schema:
            type: number
      responses:
        '200':
          description: Successfully fetched map
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/mapDevice"
  /import/gmcmap:
    post:
      description: Import a device from gmcmap.com
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                gmcmapId:
                  type: string
      responses:
        '200':
          description: Successfully started device import
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/importResult"
  /import/safecast:
    post:
      description: Import a device from safecast.org
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                safecastId:
                  type: string
      responses:
        '200':
          description: Successfully started device import
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/importResult"
  /import/uradmonitor:
    post:
      description: Import a device from uradmonitor.com
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                uradmonitorId:
                  type: string
      responses:
        '200':
          description: Successfully started device import
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/importResult"
  /import/radmon:
    post:
      description: Import a device from radmon.org
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                radmonUsername:
                  type: string
      responses:
        '200':
          description: Successfully started device import
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/importResult"
components:
  schemas:
    location:
      type: array
      nullable: true
      maxItems: 2
      minItems: 2
      items:
        type: number
    partialUser:
      type: object
      properties:
        id:
          type: string
        username:
          type: string
        admin:
          type: boolean
    device:
      type: object
      discriminator:
        propertyName: own
        mapping:
          "true": ownedDevice
          "false": device
      properties:
        id:
          type: string
        model:
          type: string
          nullable: true
        name:
          type: string
        importedFrom:
          type: string
          nullable: true
        location:
          $ref: "#/components/schemas/location"
        owner:
          $ref: "#/components/schemas/partialUser"
        disabled:
          type: boolean
        own:
          type: boolean
    ownedDevice:
      allOf:
        - $ref: "#components/schemas/device"
        - type: object
          properties:
            gmcId:
              type: integer
            lastEmailAlert:
              type: integer
            stdDevAlertLimit:
              type: integer
            proxiesSettings: ### TODO
              type: object
    mapDevice:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        location:
          $ref: "#/components/schemas/location"
        lastRecord:
          $ref: "#/components/schemas/record"
    user:
      type: object
      discriminator:
        propertyName: self
        mapping:
          "true": selfUser
          "false": user
      properties:
        id:
          type: string
        username:
          type: string
        admin:
          type: boolean
        self:
          type: boolean
        devices:
          type: array
          items:
            $ref: "#/components/schemas/device"
    selfUser:
      allOf:
        - $ref: "#components/schemas/user"
        - type: object
          properties:
            email:
              type: string
            deviceLimit:
              type: integer
            gmcId:
              type: integer
            mfa:
              type: boolean
            alertEmails:
              type: boolean
    updateUser:
      allOf:
        - $ref: "#components/schemas/user"
        - type: object
          properties:
            newPassword:
              type: string
            currentPassword:
              type: string
              description: Only required if newPassword is defined
    instanceInfo:
      type: object
      properties:
        host:
          type: string
        name:
          type: string
        about:
          type: string
        captcha:
          type: boolean
    record:
      properties:
        id:
          type: string
        deviceId:
          type: string
        cpm:
          type: number
          nullable: true
        acpm:
          nullable: true
        usv:
          type: number
          nullable: true
        co2:
          type: number
          nullable: true
        hcho:
          type: number
          nullable: true
        tmp:
          type: number
          nullable: true
        ap:
          type: number
          nullable: true
        hmdt:
          type: number
          nullable: true
        accy:
          type: number
          nullable: true
        date:
          type: integer
          nullable: true
        ip:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
        location:
          $ref: "#/components/schemas/location"
    errorResult:
      type: object
      properties:
        status:
          type: integer
        description:
          type: string
          nullable: true
        extras:
          type: object
          nullable: true
    proxyRadmon:
      type: object
      properties:
        user:
          type: string
        password:
          type: string
    proxySafecast:
      type: object
      properties:
        apiKey:
          type: string
        deviceId:
          type: integer
    proxyGmcmap:
      type: object
      properties:
        userId:
          type: integer
        deviceId:
          type: integer
    proxySettings:
      type: object
      anyOf:
        - $ref: "#/components/schemas/proxyRadmon"
        - $ref: "#/components/schemas/proxySafecast"
        - $ref: "#/components/schemas/proxyGmcmap"
    deviceStats:
      type: object
      properties:
        field:
          type: string
        device:
          type: string
        avg:
          type: number
        min:
          type: number
        max:
          type: number
        stdDev:
          type: number
        sampleSize:
          type: number
    importResult:
      type: object
      properties:
        deviceId:
          type: string