dedicated-network.yaml

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'