dedicated-network-profiles.yaml

openapi: 3.0.3
info:
  title: Dedicated Network - Network Profiles API
  description: |
    This API allows for discovering available network profiles, which are offered by the network provider to be used in conjunction of the Dedicated Network API. Network profiles describe the capabilities and performance targets of a dedicated network.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: wip
  x-camara-commonalities: 0.5
servers:
  - url: "{apiRoot}/dedicated-network-profiles/vwip"
    variables:
      apiRoot:
        default: http://localhost:9091
        description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`
paths:
  /profiles:
    get:
      tags:
        - Profiles
      summary: Read dedicated network profiles
      operationId: readNetworkProfiles
      security:
        - openId:
            - dedicated-network:profiles:read
      parameters:
        - $ref: "#/components/parameters/x-correlator"
      responses:
        '200':
          description: List of available network profiles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NetworkProfile'
        '400':
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
  /profiles/{profileId}:
    get:
      tags:
        - Profiles
      summary: Read a dedicated network profile
      operationId: readNetworkProfile
      security:
        - openId:
            - dedicated-network:profile:read
      parameters:
        - name: profileId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/NetworkProfileId"
        - $ref: "#/components/parameters/x-correlator"
      responses:
        '200':
          description: List of available network profiles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkProfile'
        '400':
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"

components:
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration

  parameters:
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        type: string
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        type: string

  schemas:
    NetworkProfileId:
      type: string

    NetworkProfile:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/NetworkProfileId'
        maxNumberOfDevices:
          type: integer
        aggregatedUlThroughput:
          $ref: "#/components/schemas/BitRate"
        aggregatedDlThroughput:
          $ref: "#/components/schemas/BitRate"
        qosProfiles:
          description: Qos Profiles, which are supported by the dedicated network.
          type: array
          items:
            type: string
          minItems: 1
        defaultQosProfile:
          description: default Qos Profiles of a device access.
          type: string
      required:
        - id
        - maxNumberOfDevices
        - aggregatedUlThroughput
        - aggregatedDlThroughput
        - qosProfiles
        - defaultQosProfile

    BitRate:
      description: Specification of bitrate
      type: object
      properties:
        value:
          description: Quantity of bitrate
          type: integer
          example: 10
          format: int32
          minimum: 1
          maximum: 1024
        unit:
          $ref: "#/components/schemas/BitRateUnitEnum"

    BitRateUnitEnum:
      description: Units of bitrate
      type: string
      enum:
        - bps
        - kbps
        - Mbps
        - Gbps
        - Tbps

    ErrorInfo:
      description: Common schema for errors
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code returned along with this error response
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description
      required:
        - status
        - code
        - message

  responses:
    Generic400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          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:
            $ref: "#/components/schemas/ErrorInfo"
          examples:
            GENERIC_401_UNAUTHENTICATED:
              description: Request cannot be authenticated
              value:
                status: 401
                code: UNAUTHENTICATED
                message: Request not authenticated due to missing, invalid, or expired credentials.
            GENERIC_401_AUTHENTICATION_REQUIRED:
              description: New authentication is needed, authentication is no longer valid
              value:
                status: 401
                code: AUTHENTICATION_REQUIRED
                message: New authentication is required.

    Generic403:
      description: Forbidden
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          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:
            $ref: "#/components/schemas/ErrorInfo"
          examples:
            GENERIC_404_NOT_FOUND:
              description: Resource is not found
              value:
                status: 404
                code: NOT_FOUND
                message: The specified resource is not found.

    Generic410:
      description: Gone
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          examples:
            GENERIC_410_GONE:
              description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available
              value:
                status: 410
                code: GONE
                message: Access to the target resource is no longer available.

    Generic500:
      description: Internal server error
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 500
            code: INTERNAL
            message: "Internal server error: ..."

    Generic503:
      description: Service Unavailable
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          examples:
            GENERIC_503_UNAVAILABLE:
              description: Service is not available. Temporary situation usually related to maintenance process in the server side
              value:
                status: 503
                code: UNAVAILABLE
                message: Service Unavailable.

  examples:

    NETWORK_STATUS_CHANGED_EXAMPLE:
      summary: Network status changed
      description: Cloud event example for network status change to ACTIVATED
      value:
        id: 625b2d4b-4da7-4f07-9169-e60ffdf7667c
        source: 'https://api.example.com/dedicated-networks/v0/networks/b69e5404-3871-448d-8f9f-11dc5d29a4c8'
        specversion: '1.0'
        type: "org.camaraproject.dedicated-networks.v0.network-status-changed"
        time: '2024-11-29T13:04:00Z'
        data:
          networkId: 'b69e5404-3871-448d-8f9f-11dc5d29a4c8'
          status: 'ACTIVATED'