Initial API Proposal for Dedicated Networks

code/API_definitions/dedicated-network-accesses.yaml

@@ -0,0 +1,405 @@
+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
+      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
+      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
+      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
+      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:
+
+  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.

code/API_definitions/dedicated-network-profiles.yaml

@@ -0,0 +1,314 @@
+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
+      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
+      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:
+
+  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'

code/API_definitions/dedicated-network.yaml

@@ -0,0 +1,631 @@
+openapi: 3.0.3
+info:
+  title: Dedicated Network - Networks API
+  description: |
+    This API allows for requesting a Dedicated Network, which provides a set of capabilities and connectivity performance targets. The Dedicated Network may be requested for a particular geographical location and at a particular time window. Depending on the requested start time for the dedicated network, the network may first enter a _reserved_ state.
+  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/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: Networks
+    description: Manage a dedicated network
+paths:
+  /networks:
+    get:
+      tags:
+        - Networks
+      summary: Get a list of dedicated networks
+      operationId: listNetworks
+      parameters:
+        - $ref: "#/components/parameters/x-correlator"
+      responses:
+        '200':
+          description: List of dedicated networks (the list can be empty)
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/NetworkInfo'
+        "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:
+        - Networks
+      summary: Request to create a dedicated network
+      operationId: createNetwork
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateNetwork'
+      parameters:
+        - $ref: "#/components/parameters/x-correlator"
+      callbacks:
+        notifications:
+          "{$request.body#/sink}":
+            post:
+              tags:
+                - Network status callback
+              summary: "Network status notifications callback"
+              description: |
+                Important: this endpoint is to be implemented by the API consumer.
+                It will be called upon change of the network request status.
+                Currently only NETWORK_STATUS_CHANGED event is defined.
+              operationId: postNotification
+              parameters:
+                - $ref: "#/components/parameters/x-correlator"
+              requestBody:
+                required: true
+                content:
+                  application/cloudevents+json:
+                    schema:
+                      $ref: "#/components/schemas/CloudEvent"
+                    examples:
+                      NETWORK_STATUS_CHANGED_EXAMPLE:
+                        $ref: "#/components/examples/NETWORK_STATUS_CHANGED_EXAMPLE"
+              responses:
+                "204":
+                  description: Successful notification
+                  headers:
+                    x-correlator:
+                      $ref: '#/components/headers/x-correlator'
+                "400":
+                  $ref: "#/components/responses/Generic400"
+                "401":
+                  $ref: "#/components/responses/Generic401"
+                "403":
+                  $ref: "#/components/responses/Generic403"
+                "410":
+                  $ref: "#/components/responses/Generic410"
+                "500":
+                  $ref: "#/components/responses/Generic500"
+                "503":
+                  $ref: "#/components/responses/Generic503"
+              security:
+                - {}
+                - notificationsBearerAuth: []
+      responses:
+        '201':
+          description: Reception acknowlegement a dedicated network request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NetworkInfo'
+          headers:
+            Location:
+              description: 'URL including the resource identifier of the newly created dedicated network.'
+              required: true
+              schema:
+                type: string
+                format: uri
+        '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"
+
+  /networks/{networkId}:
+    get:
+      tags:
+        - Networks
+      summary: Get the current information about a dedicated network
+      operationId: readNetwork
+      parameters:
+        - name: networkId
+          in: path
+          required: true
+          schema:
+            $ref: "#/components/schemas/NetworkId"
+        - $ref: "#/components/parameters/x-correlator"
+      responses:
+        '200':
+          description: Current dedicated network information
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NetworkInfo'
+        '400':
+          $ref: "#/components/responses/Generic400"
+        '404':
+          $ref: "#/components/responses/Generic404"
+    delete:
+      tags:
+        - Networks
+      summary: Destroy a dedicated network
+      operationId: deleteNetwork
+      parameters:
+        - name: networkId
+          in: path
+          required: true
+          schema:
+            $ref: "#/components/schemas/NetworkId"
+        - $ref: "#/components/parameters/x-correlator"
+      responses:
+        '204':
+          description: Successful deletion of a dedicated network
+        "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:
+    notificationsBearerAuth:
+      description: Bearer authentication for notifications
+      type: http
+      scheme: bearer
+      bearerFormat: "{$request.body#sinkCredential.credentialType}"
+
+  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:
+    NetworkId:
+      description: Network id in UUID format
+      type: string
+      format: uuid
+
+    BaseNetworkInfo:
+      description: Common attributes of a dedicated network
+      type: object
+      properties:
+        profileId:
+          $ref: 'dedicated-network-profiles.yaml#/components/schemas/NetworkProfileId'
+        serviceTime:
+          $ref: '#/components/schemas/ServiceTime'
+        serviceArea:
+          $ref: '#/components/schemas/Area'
+        sink:
+          description: Notification sink for sending notifications
+          type: string
+          format: uri
+        sinkCredential:
+          $ref: '#/components/schemas/SinkCredential'
+      required:
+        - profileId
+        - serviceTime
+        - serviceArea
+
+    NetworkInfo:
+      description: Current dedicated network information
+      allOf:
+        - $ref: "#/components/schemas/BaseNetworkInfo"
+        - type: object
+          properties:
+            id:
+              $ref: '#/components/schemas/NetworkId'
+            status:
+              $ref: '#/components/schemas/NetworkStatus'
+          required:
+            - id
+            - status
+
+    CreateNetwork:
+      description: Attributes required to create a dedicated network
+      # NOTE this design prepares for adding request specific attributes later
+      allOf:
+        - $ref: "#/components/schemas/BaseNetworkInfo"
+
+    NetworkStatus:
+      description: |
+        The current status of the requested network. The status can be one of the following:
+        * `REQUESTED` - The DN is requested, but not approved. Possible transitions to RESERVED, ACTIVATED and TERMINATED states
+        * `RESERVED` - Request is accepted by the CSP (CSP has committed the requested resources), but the Network cannot be used (outside of requested time-window)
+        * `ACTIVATED` - Network turns from reserved into Activated. Now, devices with access can use the network. Possible transitions to RESERVED or TERMINATED states
+        * `TERMINATED` - The Network resource is used and up for deletion. The API does not allow any action (except delete).
+
+      type: string
+      enum:
+        - REQUESTED
+        - RESERVED
+        - ACTIVATED
+        - TERMINATED
+
+    CloudEvent:
+      description: Event compliant with the CloudEvents specification
+      required:
+        - id
+        - source
+        - specversion
+        - type
+        - time
+      properties:
+        id:
+          description: Identifier of this event, that must be unique in the source context.
+          type: string
+        source:
+          description: Identifies the context in which an event happened in the specific Provider Implementation.
+          type: string
+          format: uri-reference
+        type:
+          description: The type of the event.
+          type: string
+          enum:
+            - "org.camaraproject.dedicated-networks.v0.network-status-changed"
+        specversion:
+          description: Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version)
+          type: string
+          enum:
+            - '1.0'
+        datacontenttype:
+          description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs'
+          type: string
+          enum:
+            - 'application/json'
+        data:
+          description: Event notification details payload, which depends on the event type
+          type: object
+        time:
+          description: |
+            Timestamp of when the occurrence happened. It must follow RFC 3339
+          type: string
+          format: date-time
+      discriminator:
+        propertyName: 'type'
+        mapping:
+          org.camaraproject.dedicated-networks.v0.network-status-changed: "#/components/schemas/EventNetworkStatusChanged"
+
+    EventNetworkStatusChanged:
+      description: Event to notify a network status change
+      type: object
+      properties:
+        data:
+          type: object
+          description: Status change details
+          required:
+            - networkId
+            - status
+          properties:
+            networkId:
+              $ref: "#/components/schemas/NetworkId"
+            status:
+              $ref: "#/components/schemas/NetworkStatus"
+      required:
+        - data
+
+    ServiceTime:
+      type: object
+      properties:
+        start:
+          type: string
+          format: date-time
+        end:
+          type: string
+          format: date-time
+      required:
+        - start
+        - end
+
+    Area:
+      description: Base schema for all areas
+      type: object
+      properties:
+        areaType:
+          $ref: "#/components/schemas/AreaType"
+      required:
+        - areaType
+      discriminator:
+        propertyName: areaType
+        mapping:
+          AREANAME: "#/components/schemas/AreaName"
+
+    AreaType:
+      type: string
+      description: |
+        Type of this area.
+        AREANAME - The area is defined by an area name
+      enum:
+        - AREANAME
+
+    AreaName:
+      description: Name of a predefined area
+      allOf:
+        - $ref: "#/components/schemas/Area"
+        - type: object
+          required:
+            - areaName
+          properties:
+            areaName:
+              type: string
+
+    SinkCredential:
+      type: object
+      properties:
+        credentialType:
+          type: string
+          enum:
+            - PLAIN
+            - ACCESSTOKEN
+            - REFRESHTOKEN
+      discriminator:
+        propertyName: credentialType
+        mapping:
+          PLAIN: '#/components/schemas/PlainCredential'
+          ACCESSTOKEN: '#/components/schemas/AccessTokenCredential'
+          REFRESHTOKEN: '#/components/schemas/RefreshTokenCredential'
+      required:
+        - credentialType
+
+    PlainCredential:
+      type: object
+      description: A plain credential as a combination of an identifier and a secret.
+      allOf:
+        - $ref: '#/components/schemas/SinkCredential'
+        - type: object
+          required:
+            - identifier
+            - secret
+          properties:
+            identifier:
+              description: The identifier might be an account or username.
+              type: string
+            secret:
+              description: The secret might be a password or passphrase.
+              type: string
+
+    AccessTokenCredential:
+      type: object
+      description: An access token credential.
+      allOf:
+        - $ref: '#/components/schemas/SinkCredential'
+        - type: object
+          properties:
+            accessToken:
+              description: REQUIRED. An access token is a previously acquired token granting access to the target resource.
+              type: string
+            accessTokenExpiresUtc:
+              type: string
+              format: date-time
+              description: REQUIRED. An absolute UTC instant at which the token shall be considered expired.
+            accessTokenType:
+              description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). For the current version of the API the type MUST be set to `Bearer`.
+              type: string
+              enum:
+                - bearer
+          required:
+            - accessToken
+            - accessTokenExpiresUtc
+            - accessTokenType
+
+    RefreshTokenCredential:
+      type: object
+      description: An access token credential with a refresh token.
+      allOf:
+        - $ref: '#/components/schemas/SinkCredential'
+        - type: object
+          properties:
+            accessToken:
+              description: REQUIRED. An access token is a previously acquired token granting access to the target resource.
+              type: string
+            accessTokenExpiresUtc:
+              type: string
+              format: date-time
+              description: REQUIRED. An absolute UTC instant at which the token shall be considered expired.
+            accessTokenType:
+              description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)).
+              type: string
+              enum:
+                - bearer
+            refreshToken:
+              description: REQUIRED. An refresh token credential used to acquire access tokens.
+              type: string
+            refreshTokenEndpoint:
+              type: string
+              format: uri
+              description: REQUIRED. A URL at which the refresh token can be traded for an access token.
+      required:
+        - accessToken
+        - accessTokenExpiresUtc
+        - accessTokenType
+        - refreshToken
+        - refreshTokenEndpoint
+
+    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'