Macrometa Waiting rooms API

openapi: 3.0.0
info:
  title: Macrometa API Reference Activity Metrics Waiting rooms API
  version: 0.17.17
  description: API reference for the Macrometa Global Data Network.
  license:
    name: Macrometa License, Version 2.0
servers:
- url: https://api-play.paas.macrometa.io
  description: GDN API
host: api-play.paas.macrometa.io
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Waiting rooms
paths:
  /api/vwr/v1/waitingrooms:
    post:
      summary: Create a waiting room
      tags:
      - Waiting rooms
      description: Creates a new waiting room with the specified properties.
      operationId: createWaitingRoom
      security:
      - APIKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WaitingRoom'
      responses:
        '202':
          description: Successfully created the waiting room.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaitingRoomPostResponse'
        '400':
          description: Bad request.
        '401':
          description: Authorization failure due to invalid authentication credentials.
        '403':
          description: Either the API key doesn't have permissions or it is deactivated.
        '500':
          description: Internal server error.
    get:
      summary: Get information on all waiting rooms
      tags:
      - Waiting rooms
      description: Retrieves a list of waiting rooms that match a specified pattern.
      operationId: getWaitingRoomUsingQueryParams
      security:
      - APIKeyAuth: []
      parameters:
      - name: pattern
        in: query
        description: Fetch waiting room information that matches the pattern. For example, a pattern could be 'aa' or 'test'. To get all waiting room, set the pattern to '*'.
        schema:
          type: string
          default: '*'
      - name: limit
        in: query
        required: false
        description: The _limit_ parameter determines the number of waiting rooms returned.
        schema:
          type: number
          default: 1000
      - name: offset
        in: query
        required: false
        description: Represents the starting point from where to begin fetching the waiting room records. This parameter is especially useful in conjunction with the _limit_ parameter for pagination of a large number of waiting room records. By default, it is set to 0, meaning that data retrieval will start from the very first record. For example, if you have 10,000 waiting room records and set the _limit_ to 100, then the first API call without an offset will retrieve records 1 to 100. If you set the _offset_ to 100 for the next call, you will retrieve records 101 to 200, and so on. This way, by incrementing the _offset_ by the _limit_ value for successive calls, you can paginate through the entire dataset.
        schema:
          type: number
          default: 0
      - name: sortby
        in: query
        required: false
        description: The field used for sorting.
        schema:
          type: string
          enum:
          - waitingroom_key
          - created_at
          - waitingroom_url
          default: waitingroom_url
      - name: order
        in: query
        required: false
        description: "The sort order:\n * _asc_ - Ascending, from A to Z\n * _desc_ - Descending, from Z to A\n"
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      responses:
        '200':
          description: Successfully fetched all waiting rooms information.
          headers:
            X-count:
              description: The total number of records that match the pattern.
              schema:
                type: number
                default: 1000
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWaitingRoomsResponse'
        '400':
          description: Bad request.
        '401':
          description: Authorization failure due to invalid authentication credentials.
        '403':
          description: Either the API key doesn't have permissions or it is deactivated.
        '404':
          description: Waiting room not found.
        '500':
          description: Internal server error.
  /api/vwr/v1/waitingrooms/{waitingroom_key}:
    get:
      summary: Get information for a specific waiting room
      tags:
      - Waiting rooms
      description: Retrieves information about a specific waiting room.
      operationId: getWaitingRoom
      security:
      - APIKeyAuth: []
      parameters:
      - name: waitingroom_key
        in: path
        description: The unique identifier for the waiting room of interest.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully fetched the waiting room information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaitingRoomObject'
        '401':
          description: Authorization failure due to invalid authentication credentials.
        '403':
          description: Either the API key doesn't have permissions or it is deactivated.
        '404':
          description: Waiting room key not found.
        '500':
          description: Internal server error.
    put:
      summary: Update a waiting room
      tags:
      - Waiting rooms
      description: Updates an existing waiting room with the specified properties.
      operationId: updateWaitingRoom
      security:
      - APIKeyAuth: []
      parameters:
      - name: waitingroom_key
        in: path
        description: A unique identifier for the waiting room.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WaitingRoomObject'
      responses:
        '201':
          description: Successfully updated the waiting room.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaitingRoomPutResponse'
        '400':
          description: Bad request.
        '401':
          description: Authorization failure due to invalid authentication credentials.
        '403':
          description: Either the API key doesn't have permissions or it is deactivated.
        '404':
          description: Waiting room key not found.
        '500':
          description: Internal server error.
    patch:
      summary: Modify specific property of a waiting room
      tags:
      - Waiting rooms
      description: Modifies an existing waiting room with one or more specified properties.
      operationId: patchWaitingRoom
      security:
      - APIKeyAuth: []
      parameters:
      - name: waitingroom_key
        in: path
        description: A unique identifier for the waiting room.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WaitingRoomObject'
      responses:
        '202':
          description: Successfully updated the waiting room.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaitingRoomObject'
        '400':
          description: Bad request.
        '401':
          description: Authorization failure due to invalid authentication credentials.
        '403':
          description: Either the API key doesn't have permissions or it is deactivated.
        '404':
          description: Waiting room key not found.
        '500':
          description: Internal server error.
    delete:
      summary: Delete waiting room information
      tags:
      - Waiting rooms
      description: Deletes waiting room configuration of a specific waiting room.
      operationId: deleteWaitingRoom
      security:
      - APIKeyAuth: []
      parameters:
      - name: waitingroom_key
        in: path
        description: The key of the waiting room to delete information for.
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Successfully deleted the waiting room.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaitingRoomDeleteResponse'
        '403':
          description: Either the API key doesn't have permissions or it is deactivated.
        '404':
          description: Waiting room key not found.
        '500':
          description: Internal server error.
components:
  schemas:
    WaitingRoom:
      allOf:
      - type: object
        required:
        - waitingroom_key
        properties:
          waitingroom_key:
            type: string
            description: The unique key of the waiting room.
      - $ref: '#/components/schemas/WaitingRoomObject'
    WaitingRoomPostResponse:
      type: object
      properties:
        waitingroom_key:
          type: string
        created_at:
          type: number
          format: number
          example: 1694757000
    WaitingRoomPutResponse:
      type: object
      properties:
        waitingroom_key:
          type: string
        updated_at:
          type: number
          format: number
          example: 1694757010
    WaitingRoomObject:
      type: object
      required:
      - waitingroom_url
      properties:
        waitingroom_url:
          type: string
          description: The URL of the waiting room.
        access_type:
          description: The access type for the waiting room.
          type: string
          enum:
          - users
          - rps
          - users_per_period
          default: users
        queue_type:
          description: The type of queue.
          type: string
          enum:
          - fifo
          - random
          - lottery
          default: fifo
        queue_mode:
          description: If set to _auto_, then the decision to enable the waiting room is determined by the traffic rate exceeding the rate limit set by rate_limit. If set to _on_, all traffic is redirected to the waiting room. If set to _off_, all requests go directly to the origin, even if the rate limit has been exceeded.
          type: string
          enum:
          - auto
          - 'on'
          - 'off'
          default: auto
        dequeue_mode:
          description: While set to _off_, keep users in the waiting room. When the value is _on_, redirect them to the origin at a rate specified by _rate_limit_.
          type: string
          enum:
          - 'on'
          - 'off'
          default: 'on'
        waiting_room_path:
          type: string
          description: Netstorage path for the waiting room HTML file. It should have the full path with "/{upload-directory-id}/path".
        metric_interval:
          type: number
          description: The time, in seconds, to enable and disable the waiting room. This time represents how long the traffic is at or above the rate limit before traffic is directed to the waiting room.
          minimum: 1
          default: 60
        rate_limit:
          type: number
          description: The rate limit for the waiting room.  The maximum users per second allowed to reach the origin.
          minimum: 1
          default: 100
        rate_period:
          type: number
          description: The period, in seconds, for the _users_per_period_ rate.
          minimum: 1
          default: 1
        max_origin_usage_time:
          type: number
          description: The amount of time, in seconds, that users can access the origin. Once a user has been granted access, the max_origin_usage_time determines how long that user can access the origin before they are forwarded to the waiting room after coming to the EdgeWorker again.
          default: 60
          minimum: 1
        waiting_room_interval:
          type: number
          description: The time interval, in seconds, when the waiting room status page is reloaded.
          default: 10
          minimum: 1
        request_priority:
          type: array
          maxItems: 10
          description: Requests may optionally specify a priority level, represented by a numerical value. A lower numerical value signifies a higher priority, ensuring these requests are processed preferentially. The array provides a list of all valid priority values available for use with this waiting room.
          items:
            type: number
            minimum: 1
            maximum: 255
            default: []
          example:
          - 1
          - 4
          - 255
        custom_attributes:
          type: object
          description: A JSON object containing custom attributes Any valid JSON can be stored here. It is not used by the waiting room at this time.
    GetWaitingRoomsResponse:
      type: array
      items:
        $ref: '#/components/schemas/WaitingRoomObject'
    WaitingRoomDeleteResponse:
      type: object
      properties:
        waitingroom_key:
          type: string
        deleted_at:
          type: number
          format: number
          example: 1694757100
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Provide an API Key to the `Authorization` header, prefixed with "apikey".


        Example: `Authorization: apikey <key>`'
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Provide a JSON Web Token (JWT) to the `Authorization` header, prefixed with "bearer".


        Example: `Authorization: bearer <jwt>`'