dedicated-network-accesses.yaml

openapi: 3.0.3
info:
  title: Dedicated Network - Network Accesses API
  description: |
    This API allows for requesting network access for devices. A device is identified by the CAMARA _device object_, containing either an MSIDSN or a Network Access Identifier.
  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-accesses/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`
tags:
  - name: Accesses
    description: Manage accesses of devices for a dedicated network
paths:

  /accesses:
    get:
      tags:
        - Accesses
      summary: Get a list of device accesses to dedicated networks, optionally filtered for a given device and/or for a given dedicated network
      operationId: listNetworkAccesses
      security:
        - openId:
            - dedicated-network:accesses:read
      parameters:
        - name: networkId
          in: query
          description: Dedicated network id
          schema:
            $ref: 'dedicated-network.yaml#/components/schemas/NetworkId'
        - $ref: "#/components/parameters/x-device"
        - $ref: "#/components/parameters/x-correlator"
      responses:
        '200':
          description: List of existing device accesses to dedicated networks, optionally filtered for a given device and/or for a dedicated network (the list can be empty)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NetworkAccessInfo'
        "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"
    post:
      tags:
        - Accesses
      summary: Create a device access to a dedicated network with given configuration
      operationId: createNetworkAccess
      security:
        - openId:
            - dedicated-network:access:create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNetworkAccess'
      responses:
        '201':
          description: Successful creation of network access for a device
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkAccessInfo'
          headers:
            Location:
              description: 'URL including the resource identifier of the newly created network access.'
              required: true
              schema:
                type: string
        '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"

  /accesses/{accessId}:
    get:
      tags:
        - Accesses
      summary: Get a device access to the dedicated network and its configuration
      operationId: readNetworkAccess
      security:
        - openId:
            - dedicated-network:access:read
      parameters:
        - name: accessId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/AccessId"
        - $ref: "#/components/parameters/x-correlator"
      responses:
        '200':
          description: A device access to the dedicated network with configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkAccessInfo'
        '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"

    delete:
      tags:
        - Accesses
      summary: Delete a device access to the dedicated network
      operationId: deleteNetworkAccess
      security:
        - openId:
            - dedicated-network:access:delete
      parameters:
        - name: accessId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/AccessId"
        - $ref: "#/components/parameters/x-correlator"
      responses:
        '204':
          description: Successful deletion of a device access
        '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
    x-device:
      name: x-device
      in: header
      description: Device object represented in a header
        Device object (#/components/schemas/Device") represented in a header.
        It is serialized according to RFC 8941 as a structured field value where
        the Device object is a dictionary, with the following additonal provisions
          - property names are changed to lower case to comply with the RFC
          - serializing property values must comply with the RFC depending on the type, and in particular
            - if the property value is a string which contains only ASCII characters, the string can be serialized as String,
              as per section 3.3.3 of the RFC
            - if the property value is a string and contains non-ASCII characters, the string must be serialized as Byte Sequence using UTF-8 encoding,
              as per section 3.3.5 of the RFC
      schema:
        type: string
      example: 'phonenumber="+123456789"'

  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        type: string

  schemas:
    AccessId:
      description: Network access id in UUID format
      type: string
      format: uuid

    BaseNetworkAccessInfo:
      description: Common attributes of a device access to a dedicated network
      type: object
      properties:
        networkId:
          $ref: "dedicated-network.yaml#/components/schemas/NetworkId"
        device:
          $ref: "#/components/schemas/Device"
        qosProfiles:
          description: (Optional) List of supported QOS profiles usable for the device. When absent, all QosProfiles of the Network are supported. Only a subset of the QOS profiles of the network is allowed
          type: array
          items:
            type: string
          minItems: 1
        defaultQosProfile:
          description: (Optional) The default QOS profile of a device access. When absent, the defaultQosProfile of the Network is used
          type: string
      required:
        - networkId
        - device

    CreateNetworkAccess:
      description: Attributes required to create a dedicated network access for a device.
      # NOTE this design prepares for adding request specific attributes later
      allOf:
        - $ref: "#/components/schemas/BaseNetworkAccessInfo"

    NetworkAccessInfo:
      description: Inforamtion about a dedicated network access for a device
      allOf:
        - $ref: "#/components/schemas/BaseNetworkAccessInfo"
        - type: object
          properties:
            id:
              $ref: "#/components/schemas/AccessId"
          required:
            - id

    Device:
      description: |
        End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.
            The developer can choose to provide the below specified device identifiers:
            * `phoneNumber`
            * `networkAccessIdentifier`
            NOTE1: the network operator might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different network operators. In this case the identifiers MUST belong to the same device.
            NOTE2: for the Commonalities release v0.4, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines.
      type: object
      properties:
        phoneNumber:
          $ref: "#/components/schemas/PhoneNumber"
        networkAccessIdentifier:
          $ref: "#/components/schemas/NetworkAccessIdentifier"
      minProperties: 1

    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"

    NetworkAccessIdentifier:
      description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator.
      type: string
      example: "123456789@domain.com"

    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.