api.yml

swagger: '2.0'
info:
  title: OpenTokRTC API
  description: >-
    OpenTokRTC App, path and API description. TO-DO: Add here a general
    description of the page navigation.
  version: 1.0.0
host: opentokdemo.tokbox.com
schemes:
  - https
basePath: /
consumes:
  - application/x-www-form-urlencoded
  - application/json
produces:
  - application/json
  - text/html
x-implementation-module: serverMethods.js
x-implementation-middleware:
  - setSecurityHeaders
  - configReady
  - securityHeaders
  - iframingOptions
  - featureEnabled
x-implementation-configuration: loadConfig
paths:
  '/':
    get:
      summary: Gets the configured index page.
      x-implemented-in: getRoot
      produces:
        - 'text/html'
      description: >-
        Returns a customized root page when the / is accessed.
      responses:
        '200':
          description: The HTML for the root page
  '/index.html':
    get:
      summary: Gets the configured index page.
      x-implemented-in: getRoot
      produces:
        - 'text/html'
      description: >-
        Returns a customized root page when the / is accessed.
      responses:
        '200':
          description: The HTML for the root page
  '/room/{roomName}':
    get:
      summary: Connects to a new or existing room.
      x-implemented-in: getRoom
      produces:
        - 'text/html,'
      description: >-
        Returns an HTML document that shows the defined UI for a chat 'room'
        where the user may or may not have specified an identity. The document
        returned will NOT have any of the information needed to connect to the
        Tokbox servers already factored in. TO-DO: ¿Queremos que esto sea así o
        que devolvamos ya todo configurado?
      parameters:
        - name: roomName
          in: path
          type: string
          description: Name of the room.
          required: true
        - name: userName
          description: Name/Id of the user that is connecting.
          in: query
          required: false
          type: string
        - name: template
          description: Desired template.
          in: query
          required: false
          type: string
      tags:
        - Rooms
      responses:
        '200':
          description: The HTML for the room
          schema:
            $ref: '#/definitions/RoomHTML'
        '400':
          description: Unknown template
          schema:
            $ref: '#/definitions/ErrorInfo'
  /updateArchiveInfo:
    post:
      summary: Callback for the OpenTok Archive API.
      x-implemented-in: postUpdateArchiveInfo
      description: Gets the updated information for a recording archive.
      parameters:
        - name: otArchiveInfo
          in: body
          schema:
            $ref: '#/definitions/OTArchiveInfo'
      tags:
        - Archives
      responses:
        '200':
          description: OK
  '/room/{roomName}/state':
    post:
      summary: Sets room state to locked or unlocked
      x-implemented-in: lockRoom
      produces:
        - 'application/json,'
      description: >-
        Returns the room info after locking operation.
      parameters:
        - name: roomName
          in: path
          description: Name of the room.
          required: true
          type: string
        - name: state
          in: body
          description: state of the room.  Can be 'locked' or 'unlocked'.
          required: true
          type: string
        - name: token
          in: body
          description: Opentok token tied to the room.
          required: true
          type: string
      tags:
        - Rooms
      responses:
        '200':
          description: Room data after successful operation
          schema:
            $ref: '#/definitions/RoomInfo'
        '400':
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorInfo'
  '/room/{roomName}/rawInfo':
    get:
      summary: Return room data if exists. Returns not found if it does not exist.
      x-implemented-in: getRoomRawInfo
      produces:
        - 'application/json,'
      description: >-
        Returns room data.
      parameters:
        - name: roomName
          in: path
          description: Name of the room.
          required: true
          type: string
      tags:
        - Rooms
      responses:
        '200':
          description: Room data
          schema:
            $ref: '#/definitions/RoomInfo'
        '400':
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorInfo'
  '/room/{roomName}/info':
    get:
      summary: Information needed to connect to the TB servers.
      x-implemented-in: getRoomInfo
      produces:
        - 'application/json,'
      description: >-
        Returns the information (sessionId, token, apiKey) that's required to
        connect to an opentok session. The sessionId returned is specific for
        the room, and the token MAY include information about the user that's
        connecting (identified as anonymous if the user didn't specify a name).
        Note that every time this URL is fetched a new token is created.
      parameters:
        - name: roomName
          in: path
          description: Name of the room.
          required: true
          type: string
        - name: userName
          in: query
          description: Name of the user.
          required: false
          type: string
      tags:
        - Rooms
      responses:
        '200':
          description: Information to connect to the room
          schema:
            $ref: '#/definitions/RoomInfo'
        '400':
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorInfo'
  '/room/{roomName}/archive':
    get:
      summary: Last archive recorded of roomName
      x-implemented-in: getRoomArchive
      produces:
        - text/html
      description: >-
        Returns the information of the last archive recorded (if it exists)  of
        the sessionId belonging to roomName
      parameters:
        - name: roomName
          in: path
          type: string
          description: Name of the room
          required: true
      responses:
        '200':
          description: OK
        '400':
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorInfo'
        '404':
          description: Archive not found
          schema:
            $ref: '#/definitions/ErrorInfo'
    post:
      summary: Starts/stop an archiving operation.
      x-implemented-in: postRoomArchive
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - 'application/json,'
      description: >-
        Starts or stops an archiving operation. Returns the information about
        the new recording, and inserts that information on the redis record
        associated to the room. Once a recording is in process, succesives call
        with operation=start are ignored and the existing record of the current
        archive is returned.
      tags:
        - Archives
      parameters:
        - name: roomName
          in: path
          description: Name of the room.
          required: true
          type: string
        - name: userName
          in: formData
          description: Name of the user.
          required: true
          type: string
        - name: operation
          in: formData
          description: Operation (startComposite/startIndividual/stop).
          required: true
          type: string
      responses:
        '200':
          description: Information about the archive being recorded
          schema:
            $ref: '#/definitions/ArchiveInfo'
        '400':
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorInfo'
  '/archive/{archiveId}':
    get:
      summary: Gets and returns a temporary archive URL.
      x-implemented-in: getArchive
      produces:
        - application/json
      description: >-
        Creates a new temporary archive URL to allow the visualization or
        download of an existing archive. The URL created is valid for 10 minutes
        only! What this API actually does is just returning a 301 with the
        actual download URL
      tags:
        - Archives
      parameters:
        - name: archiveId
          in: path
          description: Id of the archive.
          required: true
          type: string
        - name: generatePreview
          in: query
          description: >-
            If the parameter is present (the value is irrelevant) the server
            should generate and return an HTML page that embeds the video
            instead of returning the video directly.
          required: false
          type: string
      responses:
        '200':
          description: HTML with the video embedded.
          schema:
            $ref: '#/definitions/ArchiveURL'
        '301':
          description: Information to download or view the archive file.
          schema:
            $ref: '#/definitions/ArchiveURL'
        '400':
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorInfo'
    delete:
      summary: Erases an archive.
      x-implemented-in: deleteArchive
      produces:
        - application/json
      description: Erases an stored archive.
      tags:
        - Archives
      parameters:
        - name: archiveId
          in: path
          description: Id of the archive.
          required: true
          type: string
      responses:
        '200':
          description: Archive erases.
          schema:
            $ref: '#/definitions/ArchiveInfo'
        '400':
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorInfo'
  '/room/{roomName}/dial':
    post:
      summary: Starts a SIP dial-out call
      x-implemented-in: postRoomDial
      consumes:
        - application/json
      produces:
        - application/json
      description: Starts dialing a phone via a SIP gatway.
      tags:
        - Dial
      parameters:
        - name: roomName
          in: path
          description: Name of the room.
          required: true
          type: string
        - name: phoneNumber
          in: body
          description: The phone number to dial.
          required: true
          type: string
        - name: googleIdToken
          in: body
          description: Authenticated google user token to be verified before call.
          required: true
          type: string
      responses:
        '200':
          description: Information about the SIP call
          schema:
            $ref: '#/definitions/DialInfo'
        '400':
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorInfo'
        '401':
          description: Unauthorized, problem with authentication credentials.
        '403':
          description: Forbidden. Operation not valid for user token with this domain.
  '/hang-up':
    post:
      summary: Call hang-up callback for web client (to disconnect SIP connection)
      x-implemented-in: postHangUp
      consumes:
        - application/json
      produces:
        - application/json
      description: Starts dialing a phone via a SIP gatway.
      tags:
        - Dial
      parameters:
        - phoneNumber: phoneNumber
          in: body
          description: The phone number for the connection to disconnect.
          required: true
          type: string
        - name: googleIdToken
          in: body
          description: The google authentication token used to identify the client connecting.
          required: true
          type: string
      responses:
        '200':
          description: Information about the SIP call
        '400':
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorInfo'
  '/thanks':
    get:
      summary: Gets the meeting post completion page.
      x-implemented-in: getMeetingCompletion
      produces:
        - 'text/html'
      description: >-
        Returns a customized post completion page when the /thanks is accessed.
      responses:
        '200':
          description: The HTML for the meeting completion page
  '/server/health':
    get:
      summary: >-
        A health check endpoint, reporting the ability of the app to connect to external services
      x-implemented-in: getHealth
      produces:
        - application/json
      description: Starts dialing a phone via a SIP gatway.
      tags:
        - Health
      responses:
        '200':
          description: Passed health check  
          schema:
            $ref: '#/definitions/HealthInfo'
        '400':
          description: Failed health check
          schema:
            $ref: '#/definitions/HealthInfo'
definitions:
  RoomHTML:
    type: string
    description: HTML document of the room
  RoomInfo:
    type: object
    properties:
      sessionId:
        type: string
      apiKey:
        type: string
      token:
        type: string
      username:
        type: string
      isLocked:
        type: boolean
  ArchiveInfo:
    type: object
    properties:
      archiveId:
        type: string
      archiveType:
        type: string
  ArchiveURL:
    type: string
  ErrorInfo:
    type: object
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string
  OTArchiveInfo:
    type: object
    properties:
      id:
        description: Id of the updated archive
        type: string
      createdAt:
        description: >-
          The timestamp for when the archive started recording, expressed in
          milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).
        type: string
      duration:
        description: >-
          The duration of the archive in seconds. For archives that have are
          being recorded (with the status property set "started"), this value is
          set to 0.
        type: string
      name:
        description: The name of the archive you supplied (this is optional)
        type: string
      partnerId:
        description: Your OpenTok API key.
        type: string
      reason:
        description: >-
          For archives with the status "stopped", this can be set to "90 mins
          exceeded", "failure", "session ended", "user initiated". For archives
          with the status "failed", this can be set to "system failure".
        type: string
      sessionId:
        description: The session ID of the OpenTok session that was archived.
        type: string
      size:
        description: >-
          The size of the archive file. For archives that have not been
          generated, this value is set to 0.
        type: string
      status:
        description: >-
          The status of the archive. Only 'available' and 'uploaded' statuses
          are actually processed.
        type: string
      url:
        type: string
        description: >-
          The download URL of the available archive file. This is only set for
          an archive with the status set to "available"; for other archives,
          (including archives with the status "uploaded") this property is set
          to null. The download URL is obfuscated, and the file is only
          available from the URL for 10 minutes. To generate a new URL, use the
          REST API for retrieving archive information or listing archives.
  DialInfo:
    type: object
    properties:
      id:
        type: string
      connectionId:
        type: string
      streamId:
        type: string
  HealthInfo:
    type: object
    properties:
      name:
        type: string
      version:
        type: string
      gitHash:
        type: string
      opentok:
        type: boolean
      googleAuth:
        type: boolean
      status:
        type: string
        enum: [pass, fail]