webrtc-registration.yaml

openapi: 3.0.3
info:
  title: WebRTC Registration Service
  description: |-
    # Introduction
    This API provides the API consumer with the capabilities to manage
    registration and connectivity towards the network.

    The network requires that the API consumer application registers and
    identifies an end user device before enabling any media
    session services provided by the WebRTC APIs.

    A device registration created via this API will register a unique `deviceId`
    created by the API consumer (WebRTC application) and it will will provide a
    `registrationId` to manage a registration later.
    Any subsequent request from the API consumer must include the unique
    `registrationId` that will be linked to the registration previously defined.

    All operator network services are based on device registrations, this API
    allows the user to create a registration session that enable the audio/video
    functionalities exposed by the operator network.

    **Use cases to cover:**
      - Functional:
        - Ability to create Registration sessions on the network, this grants
          access to create new audio and video sessions.
        - Ability to update or remove Registration sessions on the network
      - An additional subscription to webrtc-events API is required to receive
        incoming calls.

    # Relevant terms and definitions

    - **registration** A media device session. A valid client running on a valid
      device, with permission to use the network capabilities to create and receive
      (audio/video) calls (media sessions).
    - **registrationId**: Unique identifier of an WebRTC device **registration**.
      Retrieved using the `webrtc-registration` API
    - **deviceId**: A unique identifier for the physical device where a media
      session is initiated. It is provided by the WebRTC application, it remains
      consistent across multiple installations or logins on the same device. Its
      primary function is to ensure that only one WebRTC session (**registration**)
      is active per device at a time, enabling the gateway to clean up any stale
      sessions if a new session is initiated on the same device.
    - **media session**: An exchange of media between devices.
      Typical example of session is a "single one-to-one call".
    - **mediaSessionId**: Unique identifier of a Voice or Video **session** using
      webrtc-call-handling API. Retrieved using the `webrtc-call-handling` API
    - **x-correlator**: Unique ID included in the API request created by the API consumer.
      It is used to correlate an API request with its response and help in debugging.
    - **WebRTC**: WebRTC is a free and open-source project providing web browsers
      and mobile applications with real-time communication via application programming
      interfaces. It allows audio and video communication and streaming to work
      inside web pages by allowing direct peer-to-peer communication
    - **SDP**: Acronym for Session Description Protocol. The SDP is a format for
      describing multimedia communication sessions for the purposes of announcement
      and invitation.

    # API functionality

    This API allows to create device registrations. These, identified by a unique
    `registrationId` can be updated and terminated via this API and its methods.
    - **POST**: Create a new device registration using a valid authorization token.
    - **PUT**: Update a device registration via its unique `registrationId`
    - **DELETE**: Finish an existing device registration via its unique `registrationId`
    To receive server-side updates about new voice-video sessions, you need to
    use `webrtc-events` API.

    The main concept of the API is pretty straightforward: a subscriber needs a
    session to create calls, so you will need a subscription on your device before
    attempt any audio/video call.

    Once you create a session, you can:
    - Use `webrtc-events` API to create a subscription and receive incoming calls.
    - Use `webrtc-call-handling` API to create a audio/video session and create
      an outgoing call.

    Check for extra details on each of these APIs already present on the WebRTC
    repository.

    # Authorization and authentication

    The "Camara Security and Interoperability Profile" provides details of how an
    API consumer requests an access token. Please refer to Identity and Consent
    Management (https://github.com/camaraproject/IdentityAndConsentManagement/)
    for the released version of the profile.

    The specific authorization flows to be used will be agreed upon during the
    onboarding process, happening between the API consumer and the API provider,
    taking into account the declared purpose for accessing the API, whilst also
    being subject to the prevailing legal framework dictated by local legislation.

    In cases where personal data is processed by the API and users can exercise
    their rights through mechanisms such as opt-in and/or opt-out, the use of
    three-legged access tokens is mandatory. This ensures that the API remains
    in compliance with privacy regulations, upholding the principles of
    transparency and user-centric privacy-by-design.

    # Additional CAMARA error responses

    The list of error codes in this API specification is not exhaustive.
    Therefore the API specification may not document some non-mandatory error
    statuses as indicated in `CAMARA API Design Guide`.

    Please refer to the `CAMARA_common.yaml` of the Commonalities Release
    associated to this API version for a complete list of error responses. The
    applicable Commonalities Release can be identified in the `API Readiness
    Checklist` document associated to this API version.

    As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible
    error response if it is explicitly documented in the API.

  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: wip
  x-camara-commonalities: 0.6

externalDocs:
  description: Product documentation at CAMARA
  url: https://github.com/camaraproject/WebRTC
servers:
  - url: '{apiRoot}/webrtc-registration/vwip'
    description: APIs to manage device registration and connection
    variables:
      apiRoot:
        description: API Root
        default: http://localhost:9091
tags:
  - name: Registration
    description: Operations to manage device registration with the network
paths:
  /sessions:
    post:
      tags:
        - Registration
      summary: Create a registration
      description: |-
        API endpoint used to create a new registration of a device in the network.
        It uses the `deviceId` in the request body.
        In response, a `registrationId` (in UUID format) is provided to identify
        this device registration within the network.
      operationId: createRegistration
      parameters:
        - $ref: '#/components/parameters/x-correlator'
      security:
        - openId:
            - webrtc-registration:sessions:create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/regSessionRequest'
      responses:
        '200':
          description: Ok
          headers:
            x-correlator:
              $ref: "#/components/headers/x-correlator"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/regSessionResponse'
        '400':
          $ref: "#/components/responses/CreateSessionBadRequest400"
        '401':
          $ref: "#/components/responses/Generic401"
        '403':
          $ref: "#/components/responses/CreateSessionForbidden403"
  /sessions/{registrationId}:
    put:
      tags:
        - Registration
      summary: Refresh network registration.
      description: |-
        API endpoint used to **refresh** an existing registration *before* it
        expires.

        **Server behaviour on refresh**

        1. Let `t_req` be the server-side receipt time of the request and
           `t_prev` the previously stored `registrationExpireTime`.
        2. Compute the remaining lifetime
              remaining = t_prev - t_req
           (values ≤ 0 indicate the client is late; operators MAY reject or
           treat it as a new registration).
        3. Apply the operator's configured TTL (`TTL_cfg`, e.g. 3600 s) **from
           `t_req`, not from `t_prev`**:
              newExpire = t_req + TTL_cfg
        4. Persist `newExpire` and return it in `expiresAt` inside the
           response body.

        Clients SHOULD plan to refresh well **before** `newExpire` to avoid
        race conditions.
      operationId: updateRegistrationById
      parameters:
        - $ref: '#/components/parameters/x-correlator'
        - $ref: '#/components/parameters/pathParamRegistrationId'
      security:
        - openId:
            - webrtc-registration:sessions:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/regSessionUpdate'
      responses:
        '200':
          description: Ok
          headers:
            x-correlator:
              $ref: "#/components/headers/x-correlator"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/regSessionResponse'
        '204':
          description: Updated the registration status (no content)
          headers:
            x-correlator:
              $ref: "#/components/headers/x-correlator"
        '400':
          $ref: "#/components/responses/Generic400"
        '401':
          $ref: "#/components/responses/Generic401"
        '403':
          $ref: "#/components/responses/Generic403"
        '404':
          $ref: '#/components/responses/Generic404'
    delete:
      tags:
        - Registration
      summary: Delete Registration Session.
      description: |-
        API endpoint used to remove a valid registration on the network. This action
        frees any resource and invalidates future actions that involves this
        registration between the device and the network.

        Use the registrationId to identify the registration to delete.
      operationId: deleteRegistrationById
      parameters:
        - $ref: '#/components/parameters/x-correlator'
        - $ref: '#/components/parameters/pathParamRegistrationId'
      security:
        - openId:
            - webrtc-registration:sessions:delete
      responses:
        '204':
          description: No Content
          headers:
            x-correlator:
              $ref: "#/components/headers/x-correlator"
        '400':
          $ref: "#/components/responses/Generic400"
        '401':
          $ref: "#/components/responses/Generic401"
        '403':
          $ref: "#/components/responses/Generic403"
        '404':
          $ref: '#/components/responses/Generic404'
components:
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        $ref: "#/components/schemas/XCorrelator"
  parameters:
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        $ref: "#/components/schemas/XCorrelator"
    pathParamRegistrationId:
      name: registrationId
      in: path
      description: The registrationId assigned by the registration service
      required: true
      style: simple
      explode: false
      schema:
        type: string
  schemas:
    XCorrelator:
      type: string
      pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
      example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
    regSessionRequest:
      type: object
      required:
        - deviceId
      properties:
        deviceId:
          type: string
          pattern: uuid
          description: |-
            The deviceId of the client in UUID format. A unique identifier for
            the physical device where a registration is initiated. Generated
            by the WebRTC application, and consistent within the same device.
        registrationExpireTime:
          type: string
          format: date-time
          description: |-
            Optional **absolute** expiry moment for this registration.
            It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.

            ▸ **Devices without a trustworthy clock** (e.g. Wi-Fi-only tablets
              or other non-SIM hardware) SHOULD treat the value as an
              **upper bound**.  Such devices MAY derive a local time-to-live:

                  ttl = registrationExpireTime - now()

              and initiate a refresh *before* `ttl` elapses (a safety margin
              of ~120 s is recommended).

            ▸ If the client omits this field, the server will set the expiry
              according to its own TTL policy and return the resulting
              `registrationExpireTime` in the response.
    regSessionResponse:
      type: object
      required:
        - registrationId
      properties:
        regInfo:
          $ref: '#/components/schemas/RegistrationInformation'
        registrationId:
          type: string
          description: The registration session ID is returned when registering a device with the network . Clients must utilize this ID to as a parameter in the call-handling and subscription APIs.
        expiresAt:
          type: string
          format: date-time
          description: |-
            Authoritative expiry timestamp calculated **after** applying the
            refresh logic. Clients MUST treat this value as the new upper-bound
            and schedule their next refresh accordingly.

            Client applications should compute the remaining time before expiry (expiresAt - currentTime)
            and plan to refresh well in advance to avoid race conditions. A suggested margin is 120 seconds before expiry.

            It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
    regSessionUpdate:
      type: object
      properties:
        registrationExpireTime:
          type: string
          format: date-time
          description: |-
            Optional **absolute** UTC timestamp that *requests* a new expiry.
            The server will honour the value only if it is **later than the
            operator's minimum TTL** and **earlier than operator maximum TTL**;
            otherwise it falls back to its own policy (see refresh algorithm
            above).

            If omitted, the server always extends the expiry by its configured
            TTL, measured from the moment the refresh is received.

            It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
    RegistrationStatus:
      type: string
      enum:
        - Registered
    RegistrationInformation:
      type: object
      properties:
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumber'
        regStatus:
          $ref: '#/components/schemas/RegistrationStatus'
    ErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: Friendly Code to describe the error
        message:
          type: string
          description: A human readable description of what the event represent
    PhoneNumber:
      description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
      type: string
      pattern: '^\+[1-9][0-9]{4,14}$'
      example: "+123456789"

  responses:
    # Method specific responses
    CreateSessionBadRequest400:
      description: Bad Request
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 400
                  code:
                    enum:
                      - INVALID_ARGUMENT
                      - OUT_OF_RANGE
                      - EMERGENCY_ADDRESS_MISSING
          examples:
            GENERIC_400_INVALID_ARGUMENT:
              description: Invalid Argument. Generic Syntax Exception
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or query param.
            GENERIC_400_OUT_OF_RANGE:
              description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested
              value:
                status: 400
                code: OUT_OF_RANGE
                message: Client specified an invalid range.
            GENERIC_400_EMERGENCY_ADDRESS_MISSING:
              description: Specific Syntax Exception regarding emergency address that is relevant in the context of the API
              value:
                status: 400
                code: EMERGENCY_ADDRESS_MISSING
                message: Emergency address missing
    CreateSessionForbidden403:
      description: Forbidden
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 403
                  code:
                    enum:
                      - PERMISSION_DENIED
                      - INVALID_TOKEN_CONTEXT
                      - MAX_REGISTRATION_PER_USER
                      - MAX_REGISTRATION_PER_MSISDN
                      - MAX_DEVICES_PER_USER
          examples:
            CREATE_403_PERMISSION_DENIED:
              description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
              value:
                status: 403
                code: PERMISSION_DENIED
                message: Client does not have sufficient permissions to perform this action.
            CREATE_403_INVALID_TOKEN_CONTEXT:
              description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token
              value:
                status: 403
                code: INVALID_TOKEN_CONTEXT
                message: "device is not consistent with access token."
            CREATE_403_MAX_REGISTRATION_PER_USER:
              # summary: Max registration per user
              value:
                status: 403
                code: MAX_REGISTRATION_PER_USER
                message: 'The maximum number of service registrations per user has been reached'
            CREATE_403_MAX_REGISTRATION_PER_MSISDN:
              # summary: Max registration per MSISDN
              value:
                status: 403
                code: MAX_REGISTRATION_PER_MSISDN
                message: 'The maximum number of service registrations per MSISDN has been reached'
            CREATE_403_MAX_DEVICES_PER_USER:
              # summary: Max devices per user
              value:
                status: 403
                code: MAX_DEVICES_PER_USER
                message: 'The maximum number of device instances per user has been reached'
    # Generic responses
    Generic400:
      description: Bad Request
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 400
                  code:
                    enum:
                      - INVALID_ARGUMENT
                      - OUT_OF_RANGE
          examples:
            GENERIC_400_INVALID_ARGUMENT:
              description: Invalid Argument. Generic Syntax Exception
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or query param.
            GENERIC_400_OUT_OF_RANGE:
              description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested
              value:
                status: 400
                code: OUT_OF_RANGE
                message: Client specified an invalid range.
    Generic401:
      description: Unauthorized
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 401
                  code:
                    enum:
                      - UNAUTHENTICATED
          examples:
            GENERIC_401_UNAUTHENTICATED:
              description: Request cannot be authenticated and a new authentication is required
              value:
                status: 401
                code: UNAUTHENTICATED
                message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required.
    Generic403:
      description: Forbidden
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 403
                  code:
                    enum:
                      - PERMISSION_DENIED
                      - INVALID_TOKEN_CONTEXT
          examples:
            GENERIC_403_PERMISSION_DENIED:
              description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
              value:
                status: 403
                code: PERMISSION_DENIED
                message: Client does not have sufficient permissions to perform this action.
            GENERIC_403_INVALID_TOKEN_CONTEXT:
              description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token
              value:
                status: 403
                code: INVALID_TOKEN_CONTEXT
                message: "{{field}} is not consistent with access token."
    Generic404:
      description: Not found
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 404
                  code:
                    enum:
                      - NOT_FOUND
                      - IDENTIFIER_NOT_FOUND
          examples:
            GENERIC_404_NOT_FOUND:
              description: Resource is not found
              value:
                status: 404
                code: NOT_FOUND
                message: The specified resource is not found.
            GENERIC_404_IDENTIFIER_NOT_FOUND:
              description: Some identifier cannot be matched to a device
              value:
                status: 404
                code: IDENTIFIER_NOT_FOUND
                message: Device identifier not found.