api_docs.yml

openapi: 3.0.0
info:
  title: UNC AI Surveillance API
  version: 0.0.1
components:
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
tags:
  - name: Users
    description: Operations related to users
  - name: Areas
    description: Operations related to areas
  - name: Violations
    description: Operations related to violations
  - name: Cameras
    description: Operations related to cameras
paths:
  /users/current:
    get:
      summary: Get information of current user
      tags:
        - Users
      security:
        - jwt: ["json web token"]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The user's ID
                  username:
                    type: string
                    description: The username
                  first-name:
                    type: string
                    description: The user's first-name
                  last-name:
                    type: string
                    description: The user's last-name
                  assigned-role:
                    type: integer
                    description: 1 = Security Guard, 2 = Security Head, 3 = Administrator
              example:
                assigned-role: 1
                last-name: LeBlanc
                id: d6ab56e9-52d1-4609-9aad-40595e57eed4
                first-name: Rio
                username: rio
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
  /users/login:
    post:
      summary: Login user
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                password:
                  type: string
                device-os:
                  type: string
                device-signature:
                  type: string
                device-name:
                  type: string
            example:
              username: "admin"
              password: "Arcon#123"
              device-os: "windows"
              device-name: "Asus ROG Zephyrus M16"
              device-signature: "4b44829fa912965a"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  jwt:
                    type: string
                    description: The json web token
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message

  /users/register:
    post:
      summary: Get information of current user
      tags:
        - Users
      security:
        - jwt: ["json web token"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: The username
                first-name:
                  type: string
                  description: The user's first-name
                last-name:
                  type: string
                  description: The user's last-name
                password:
                  type: string
                  description: The user's last-name
                assigned-role:
                  type: integer
                  description: 1 = Security Guard, 2 = Security Head, 3 = Administrator
            example:
              assigned-role: 1
              last-name: LeBlanc
              password: Arcon#123
              first-name: Rio
              username: rio
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The user's ID
              example:
                id: d6ab56e9-52d1-4609-9aad-40595e57eed4
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
                example:
                  message: "Username taken"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
                example:
                  message: "Failed to register user"
  /users/unassigned:
    post:
      summary: Get all unassigned guards
      tags:
        - Users
      security:
        - jwt: ["json web token"]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                properties:
                  id:
                    type: string
                    description: The user's id
                  first-name:
                    type: string
                    description: The user's first-name
                  last-name:
                    type: string
                    description: The user's last-name
            example:
              - id: 1552f5ec-c2cc-47b7-bed5-761c0361960d,
                last-name: LeBlanc,
                first-name: Funk"

              - id: 1552f5ec-c2cc-47b7-bed5-761c0361920d,
                last-name: Uzumaki,
                first-name: Goku"

      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The user's ID
              example:
                id: d6ab56e9-52d1-4609-9aad-40595e57eed4
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
  /users/avatar:
    patch:
      summary: Set current user's avatar
      tags:
        - Users
      security:
        - jwt: ["json web token"]
      responses:
        "204":
          description: No Content (Everything's good)
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
      requestBody:
        description: "Expect a multipart containing the image"
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  description: "Must be image type"
                  type: string
                  format: binary
              required:
                - image
            encoding:
              image:
                contentType: image/jpeg
    delete:
      summary: Clear current user's avatar
      tags:
        - Users
      security:
        - jwt: ["json web token"]
      responses:
        "204":
          description: No Content (Everything's good)
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
    get:
      summary: Get specified user avatar (if no parameter then current user)
      tags:
        - Users
      parameters:
        - name: id
          in: query
          description: User ID (Optional)
          required: false
          schema:
            type: string
            nullable: true
      security:
        - jwt: ["json web token"]
      responses:
        "200":
          description: OK
          content:
            image/jpeg:
              schema:
                format: binary
              example: "no example its jpeg"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
  /areas/list:
    get:
      summary: Get all areas
      tags:
        - Areas
      security:
        - jwt: ["json web token"]
      parameters:
        - name: count-guards
          in: query
          description: Returns including count
          required: false
          schema:
            type: boolean
            nullable: true
            default: false
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    code:
                      type: string
                      description: The area's code
                    name:
                      type: string
                      description: The area's name
                    guard-count:
                      type: integer
                      nullable: true
              examples:
                "count-guards=false|null":
                  value:
                    - code: JH-01
                      name: JH Hallway 1
                    - code: JH-02
                      name: JH Hallway 2
                count-guards=true:
                  value:
                    - code: JH-01
                      name: JH Hallway 1
                      guard-count: 2,
                    - code: JH-02
                      name: JH Hallway 2
                      guard-count: 5,

        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
  /areas/create:
    post:
      summary: Create area
      tags:
        - Areas
      security:
        - jwt: ["json web token"]

      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    code:
                      type: string
                      description: The area's code
                    name:
                      type: string
                      description: The area's name
              example:
                items:
                  - code: JH-01
                    name: JH Hallway 1
                  - code: JH-02
                    name: JH Hallway 2
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
  /areas/remove:
    delete:
      summary: Remove area
      tags:
        - Areas
      security:
        - jwt: ["json web token"]
      parameters:
        - name: area-code
          in: query
          description: Area Code
          required: true
          schema:
            type: string
            nullable: false
          example: "AMS-03"
      responses:
        "200":
          description: OK
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
  /areas/assign:
    patch:
      summary: Assign guard to area
      tags:
        - Areas
      security:
        - jwt: ["json web token"]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user-id:
                  type: string
                area-code:
                  type: string
                  nullable: true
            examples:
              assign to area:
                value:
                  area-code: "GT2"
                  user-id: "e863187f-f093-48f8-8f2e-68f1c2b6ceb7"
              unassign:
                value:
                  user-id: "e863187f-f093-48f8-8f2e-68f1c2b6ceb7"
      responses:
        "200":
          description: OK
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message

  /areas/camera:
    post:
      summary: Add camera into an area,
      tags:
        - Cameras
      security:
        - jwt: ["json web token"]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                area-code:
                  type: string
                  maxLength: 10
                  minLength: 3
                label:
                  type: string
                  maxLength: 15
                  minLength: 3
                camera-url:
                  type: string
                  maxLength: 512
                  minLength: 10
                enable:
                  type: boolean
            example:
              area-code: "JH-C1"
              label: "JH Camera 1"
              camera-url: "rtsp://192.168.100.2:9077/h264_ulaw.sdp"
              enable: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Camera id
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        "404":
          description: Not Found (When area code doesn't exists),
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        "409":
          description: Conflict (When similar camera label)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
    patch:
      summary: Modify camera
      tags:
        - Cameras
      security:
        - jwt: ["json web token"]
      requestBody:
        description: Label and Camera URL are optional but both of them not specified or null will lead to an error. Specify both or either one of the two.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  description: "Camera UUID"
                  type: string
                label:
                  type: string
                  maxLength: 15
                  minLength: 3
                  nullable: true
                camera-url:
                  type: string
                  maxLength: 512
                  minLength: 10
                  nullable: true
            example:
              id: "fb13efca-5b84-44d7-b017-6dd04651c198"
              label: "JH Camera 1"
              camera-url: "rtsp://192.168.100.2:9077/h264_ulaw.sdp"
      responses:
        "204":
          description: No Content (Everything's fine)
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        "404":
          description: Not Found (When ID doesn't exists),
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
    delete:
      summary: Delete camera
      tags:
        - Cameras
      parameters:
        - name: id
          in: query
          description: Camera ID
          required: true
          schema:
            type: string
            nullable: false
          example: "a08f7868-fe33-4d82-98e8-fbd8b493e725"
      security:
        - jwt: ["json web token"]
      responses:
        "204":
          description: No Content (Everything's fine)
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        "404":
          description: Not Found (When ID doesn't exists),
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
  /violations/unidentified:
    get:
      summary: Retrieve all unidentified violators
      tags:
        - Violations
      security:
        - jwt: ["json web token"]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    id:
                      type: string
                    area-code:
                      type: string
                    violation-kind:
                      type: integer
                      description: "1 = Facemask Violation, 2 = Foot Traffic"
                    date-time:
                      type: string
                      description: "Date and Time in UTC"
              example:
                id: "3aed09ed-a1b0-4da6-8338-103e64798386"
                area-code: "GT2"
                violation-kind: 1
                date-time: "2023-04-01T14:23:09.850544"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
  /violations/identified:
    get:
      summary: Retrieve all identified violators
      tags:
        - Violations
      security:
        - jwt: ["json web token"]
      parameters:
        - name: area-code
          in: query
          description: Area Code (Optional)
          required: false
          schema:
            type: string
            nullable: true
          example: "JH-03"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    id:
                      type: string
                    area-code:
                      type: string
                    violation-kind:
                      type: integer
                      description: "1 = Facemask Violation, 2 = Foot Traffic"
                    date-time:
                      type: string
                      description: "Date and Time in UTC"
                    first-name:
                      type: string
                    last-name:
                      type: string
                    category:
                      type: integer
                      description: "Student = 1, Visitor = 2, Faculty = 3, Staff = 4"
              example:
                - violation-id: "3aed09ed-a1b0-4da6-8338-103e64798386"
                  area-code: "GT2"
                  violation-kind: 1
                  date-time: "2011-07-01 06:30:30+00"
                  personnel-id: "d6da2834-6236-4ac2-b3ed-9e1413cccab9"
                  first-name: Jane
                  last-name: Doe,
                  category: 2
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
  /violations/image:
    post:
      summary: Retrieve the violators image in jpeg
      tags:
        - Violations
      security:
        - jwt: ["json web token"]
      parameters:
        - name: id
          in: query
          description: Violation ID
          required: true
          schema:
            type: string
            nullable: true
            default: false
          example: "5ca126b1-ce37-4bf5-b7d2-0ca11ad7e19a"
      responses:
        "200":
          description: OK
          content:
            image/jpeg:
              schema:
                format: binary
              example: "no example its jpeg"

        "404":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
        "401":
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
  /violation/record:
    patch:
      summary: Record details of violators (Can be use to modify)
      tags:
        - Violations
      security:
        - jwt: ["json web token"]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                violation-id:
                  type: string
                last-name:
                  type: string
                first-name:
                  type: string
                category:
                  type: integer
                  description: "Student = 1, Visitor = 2, Faculty = 3, Staff = 4"
            example:
              violation-id: "e863187f-f093-48f8-8f2e-68f1c2b6ceb7"
              first-name: John
              last-name: Doe
              category: 1
      responses:
        "200":
          description: OK
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message