iot-network-optimization.yaml

---
openapi: 3.0.3
############################################################################
#                                     API info                             #
############################################################################
info:
  title: IoT Network Optimization API
  description: |
    ## Overview
    The IoT Network Optimization API provides the API Consumer with the
    capabilities of activating IoT-specific features for a fleet of devices.
    ## Introduction
    The scenario a Service Provider that partners with a Telco Operator to
    deploy IoT devices (e.g., sensors, trackers) across the Telco’s nationwide
    cellular network.
    To ensure prolonged device battery life and operational efficiency, the
    Service Provider seeks to activate power-saving configurations for its IoT
    fleet during periods of low activity or based on predefined thresholds.
    The Service Provider’s management system invokes the IoT Network
    Optimization API to dynamically adjust network connectivity parameters.
    This includes optimizing data transmission intervals, reducing signal
    strength during idle phases, and scheduling sleep cycles for devices
    without disrupting critical service functionality. The API evaluates
    network conditions, device locations, and application requirements to apply
    energy-efficient settings while maintaining guaranteed quality-of-service
    levels. By leveraging the API, the Provider ensures IoT devices consume
    minimal power during operation, significantly extending battery lifetimes
    and reducing energy costs. The optimization accounts for both device-level
    energy savings and reduced overhead on the Telco’s network infrastructure
    (e.g., lower RAN utilization during sleep cycles). Clients benefit from
    uninterrupted service with no manual
    intervention, aligning sustainability goals with operational reliability.\
    \
    **Example use case and flow:**\
    \
    [**Service**](https://github.com/camaraproject/\
    IoTNetworkOptimization/blob/main/documentation/API_documentation/\
    IoT_Network_Optimization_UserStory_UseCase_1.md)\
    \
    **The main elements of the IoT Network Optimization API are:**\
    \
    **PowerSavingRequest:**
    Provides to the API Producer the intention of a enabling or disabling power
    saving features for a specific set of IoT devices.\
    \
    **PowerSavingResponse:**
    Provides to the API Consumer the status of the power-saving feature
    activation based on the related transaction.\
    # Authorization and authentication
    The "Camara Security and Interoperability Profile" provides details on how
    an API consumer requests an access token. Please refer to Identify and
    Consent Management
    (https://github.com/camaraproject/IdentityAndConsentManagement/)
    for the released version of the profile.\
    \
    The specific authorization flows to be used will be agreed upon during the
    onboarding process, happening between the API consumer and the API
    provider, taking into account the declared purpose for accessing the API,
    whilst also being subject to the prevailing legal framework dictated by
    local legislation.\
    \
    In cases where personal data is processed by the API and users can
    exercise their rights through mechanisms such as opt-in and/or opt-out,
    the use of three-legged access tokens is mandatory. This ensures that
    the API remains in compliance with privacy regulations, upholding the
    principles of transparency and user-centric privacy-by-design.
    ## API Documentation
    ## Details
    The IoT Network Optimization API provides the API Consumer with the
    capability to activate and manage IoT-specific network features for a fleet
    of connected devices. The API enables optimized power consumption
    transmission by leveraging network-level configurations tailored for IoT
    deployments.

    The IoT API allows an IoT Service Provider to dynamically adjust network
    parameters to optimize device performance and reduce operational overhead.
    The IoT API Consumer (typically the IoT Service Provider or a third-party
    management system) invokes the API with identifiers for the target IoT
    devices. The API then applies the requested optimizations, such as enabling
    low-power modes for battery-operated sensors.

    By using the IoT Network Optimization API, Service Providers can ensure
    their IoT deployments operate at peak efficiency extending device battery
    life and improving overall service reliability.

    The IoT Network Optimization API is an intent based API.
    \
    The IoT Network Optimization API supports the following Intent:
    - Intent1: I would like to activate power-saving features for my IoT
    devices during a specified period.

    The inputs for the above intent are:
    - IoT devices (e.g., device identifiers like IPs or SIM phone number)
    - power-saving desired status
    - time frame (e.g., start/end timestamps)

    The output for the above intent are:
    - activation status (success/failure per device or group)
    - transaction ID for tracking

    The related endpoint is:
    - Intent: /features/power-saving

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

    Please refer to [CAMARA_common.yaml]({link_to_release}/CAMARA_common.yaml)
    for a complete list of error responses.

    As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible
    error response if it is explicitly documented in the API.
    ## FAQ's
    (FAQs will be added in a later version of the documentation)
    ## Release Notes
    First draft for the IoT Network Optimization API.

  version: wip
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-camara-commonalities: 0.5
externalDocs:
  description: Product documentation at Camara
  url: https://github.com/camaraproject/IoTNetworkOptimization
############################################################################
#                                     Servers                              #
############################################################################
servers:
  - url: "{apiRoot}/iot-network-opt/vwip"
    variables:
      apiRoot:
        default: http://localhost:9091
        description: API root for the IoT Network Optimization API
security:
  - notificationsBearerAuth: []
tags:
  - name: Power Saving
    description: Enable/Disable power-saving features.
############################################################################
#                                     Paths                                #
############################################################################
paths:
  /features/power-saving:
    post:
      tags:
        - Power Saving
      summary: Activate or de-activate power-saving features for IoT devices
      operationId: activatePowerSaving
      parameters:
        - $ref: '#/components/parameters/x-correlator'
      security:
        - oAuth2:
            - 'iot-management:power-saving:write'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PowerSavingRequest'
      responses:
        "202":
          description: Power-saving feature request accepted
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PowerSavingResponse'
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "409":
          $ref: "#/components/responses/Generic409"
        "501":
          $ref: "#/components/responses/Generic501"
      callbacks:
        onTransactionCompleted:
          $ref: "#/components/callbacks/onTransactionCompleted"
  /features/power-saving/transactions/{transactionId}:
    get:
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TransactionId'
        - $ref: '#/components/parameters/x-correlator'
      tags:
        - Power Saving
      summary: Get status of a transaction for power-saving features
      operationId: getPowerSaving
      security:
        - oAuth2:
            - 'iot-management:power-saving:read'
      responses:
        "200":
          description: Power-saving features activated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PowerSavingResponse'
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "501":
          $ref: "#/components/responses/Generic501"

############################################################################
#                                 Components                               #
############################################################################
components:
  securitySchemes:
    oAuth2:
      type: oauth2
      description: This API uses OAuth 2
        [More info](https://api.example.com/docs/auth)
      flows:
        clientCredentials:
          tokenUrl: 'https://example.com/oauth/token'
          scopes:
            'iot-management:power-saving:read':
              Grants access to read-only data in the Power Saving resources
            'iot-management:power-saving:write':
              Grants write access to the Power Saving resources
    notificationsBearerAuth:
      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:
        $ref: "#/components/schemas/XCorrelator"
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        $ref: "#/components/schemas/XCorrelator"
  #########################################################################
  #                             Events/Callbacks                          #
  #########################################################################
  callbacks:
    onTransactionCompleted:
      # when data is sent, it will be sent to the callback url provided
      "{$request.body#/subscriptionRequest/sink}":
        post:
          summary: Provides back the result of the enabling operations
          description: |
            once the system has request to enable power-settings for all
            the devices it collects the results and provides it back to
            the API Consumer
          operationId: IoTNetworkOptimizationNotification
          parameters:
            - $ref: '#/components/parameters/x-correlator'
          security:
            - notificationsBearerAuth: []
          requestBody:
            description: payload containing the operation results
            required: true
            content:
              application/cloudevents+json:
                schema:
                  allOf:
                    - $ref: '#/components/schemas/CloudEvent'
                  example:
                    id: "string"
                    source: "https://notificationSendServer12.example.com"
                    type: "org.camaraproject.iot-network-optimization-notification.v1.power-saving"
                    specversion: "1.0"
                    datacontenttype: "application/json"
                    data:
                      activationStatus:
                        - device:
                            phoneNumber: "+123456789"
                            networkAccessIdentifier: "123456789@domain.com"
                            ipv4Address:
                              publicAddress: "84.125.93.10"
                              publicPort: 59765
                            ipv6Address: "2001:db8:85a3:8d3:1319:8a2e:370:7344"
                          status: "pending"
                      transactionId: "string"
                    time: "2018-04-05T17:31:00Z"
          responses:
            "202":
              description: Your server implementation should return this HTTP
                status code if the data was received successfully
              headers:
                x-correlator:
                  $ref: '#/components/headers/x-correlator'
            "204":
              description: Your server should return this HTTP status code if
               no longer interested in further updates
              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"
            "429":
              $ref: "#/components/responses/Generic429"
  ############################################################################
  #                                 Resources                                #
  ############################################################################
  schemas:
    SubscriptionRequest:
      description: The request for creating a event-type event subscription
      type: object
      required:
        - sink
        - protocol
        - config
        - types
      properties:
        protocol:
          $ref: "#/components/schemas/Protocol"
        sink:
          type: string
          format: uri
          pattern: ^https:\/\/.+$
          description: The address to which events shall be delivered using the selected protocol.
          example: "https://endpoint.example.com/sink"
        sinkCredential:
          $ref: "#/components/schemas/SinkCredential"
        types:
          description: |
            Camara Event types eligible to be delivered by this subscription.
            Note: the maximum number of event types per subscription will be decided at API project level
          type: array
          minItems: 1
          maxItems: 2
          items:
            $ref: "#/components/schemas/SubscriptionEventType"
        config:
          $ref: "#/components/schemas/Config"
      discriminator:
        propertyName: protocol
        mapping:
          HTTP: "#/components/schemas/HTTPSubscriptionRequest"
    HTTPSubscriptionRequest:
      allOf:
        - $ref: "#/components/schemas/SubscriptionRequest"
        - type: object
          properties:
            protocolSettings:
              $ref: "#/components/schemas/HTTPSettings"
    HTTPSettings:
      type: object
      properties:
        headers:
          type: object
          description: |-
            A set of key/value pairs that is copied into the HTTP request as custom headers.

            NOTE: Use/Applicability of this concept has not been discussed in Commonalities under the scope of Meta Release v0.4. When required by an API project as an option to meet a UC/Requirement, please generate an issue for Commonalities discussion about it.
          additionalProperties:
            type: string
        method:
          type: string
          description: The HTTP method to use for sending the message.
          enum:
            - POST

    Protocol:
      type: string
      enum: ["HTTP", "MQTT3", "MQTT5", "AMQP", "NATS", "KAFKA"]
      description: Identifier of a delivery protocol. Only HTTP is allowed for now
      example: "HTTP"
    Config:
      description: |
        Implementation-specific configuration parameters needed by the subscription manager for acquiring events.
        In CAMARA we have predefined attributes like `subscriptionExpireTime`, `subscriptionMaxEvents`, `initialEvent`
        Specific event type attributes must be defined in `subscriptionDetail`
        Note: if a request is performed for several event type, all subscribed event will use same `config` parameters.
      type: object
      required:
        - subscriptionDetail
      properties:
        subscriptionDetail:
          $ref: "#/components/schemas/CreateSubscriptionDetail"
        subscriptionExpireTime:
          type: string
          format: date-time
          example: 2023-01-17T13:18:23.682Z
          description: The subscription expiration time (in date-time format) requested by the API consumer. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Up to API project decision to keep it.
        subscriptionMaxEvents:
          type: integer
          description: Identifies the maximum number of event reports to be generated (>=1) requested by the API consumer - Once this number is reached, the subscription ends. Up to API project decision to keep it.
          minimum: 1
          example: 5
        initialEvent:
          type: boolean
          description: |
            Set to `true` by API consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request.
            Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered
            Up to API project decision to keep it.
    SinkCredential:
      description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target.
      type: object
      example:
        credentialType: ACCESSTOKEN
      properties:
        credentialType:
          type: string
          enum:
            - PLAIN
            - ACCESSTOKEN
            - REFRESHTOKEN
          description: |
            The type of the credential.
            Note: Type of the credential - MUST be set to ACCESSTOKEN for now
      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) timestamp at which the token shall be considered expired.
                In the case of an ACCESS_TOKEN_EXPIRED termination reason, implementation should notify the client before the expiration date.
                If the access token is a JWT and registered "exp" (Expiration Time) claim is present, the two expiry times should match.
                It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
              example: "2023-07-03T12:27:08.312Z"
            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
          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) timestamp at which the token shall be considered expired.
                In the case of an ACCESS_TOKEN_EXPIRED termination reason, implementation should notify the client before the expiration date.
                If the access token is a JWT and registered "exp" (Expiration Time) claim is present, the two expiry times should match.
                It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
              example: "2023-07-03T12:27:08.312Z"
            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
    CreateSubscriptionDetail:
      description: The detail of the requested event subscription.
      type: object
    EventTypeNotification:
      type: string
      description: Event triggered when an event-type event occurred.
      enum:
        - org.camaraproject.iot-network-optimization-notification.v1.power-saving
        - org.camaraproject.iot-network-optimization-notification.v1.power-saving.error
    SubscriptionEventType:
      type: string
      description: |
        event-type that could be subscribed through this subscription. Several event-type could be defined.
      enum:
        - org.camaraproject.iot-network-optimization-notification.v1.power-saving
        - org.camaraproject.iot-network-optimization-notification.v1.power-saving.error
    PowerSavingRequest:
      type: object
      required:
        - devices
        - enabled
        - subscriptionRequest
      properties:
        devices:
          type: array
          items:
            $ref: '#/components/schemas/Device'
          description: Device IDs or group identifiers
        enabled:
          type: boolean
        timePeriod:
          required:
            - startDate
          properties:
            startDate:
              type: string
              format: date-time
              description: An instant of time, starting of the TimePeriod.
            endDate:
              type: string
              format: date-time
              description: An instant of time, ending of the TimePeriod.
                If not included, then the period has no ending date.
        subscriptionRequest:
          $ref: '#/components/schemas/SubscriptionRequest'
    DateTime:
      type: string
      format: date-time
      description: |
        Timestamp of when the occurrence happened. Must adhere to RFC 3339.
        WARN: This optional field in CloudEvents specification is required in
        CAMARA APIs implementation.
      example: '2018-04-05T17:31:00Z'
    Source:
      type: string
      format: uri-reference
      minLength: 1
      description: |
        Identifies the context in which an event happened - be a non-empty
        `URI-reference` like:
        - URI with a DNS authority:
          * https://github.com/cloudevents
          * mailto:cncf-wg-serverless@lists.cncf.io
        - Universally-unique URN with a UUID:
          * urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66
        - Application-specific identifier:
          * /cloudevents/spec/pull/123
          * 1-555-123-4567
      example: "https://notificationSendServer12.supertelco.com"
    CloudEvent:
      description: The notification callback
      required:
        - id
        - source
        - specversion
        - type
        - time
      properties:
        id:
          type: string
          description: identifier of this event, that must be unique in the
            source context.
          minLength: 1
        source:
          $ref: '#/components/schemas/Source'
        type:
          $ref: "#/components/schemas/EventTypeNotification"
        specversion:
          type: string
          description: Version of the specification to which this event conforms
            (must be 1.0 if it conforms to cloudevents 1.0.2 version)
          enum:
            - "1.0"
        datacontenttype:
          type: string
          description: 'media-type that describes the event payload encoding,
            must be "application/json" for CAMARA APIs'
          enum:
            - application/json
        data:
          type: object
          description: Event details payload described in each CAMARA API and
            referenced by its type
        time:
          $ref: "#/components/schemas/DateTime"
      discriminator:
        propertyName: "type"
        mapping:
          org.camaraproject.iot-network-optimization-notification.v1.power-saving: "#/components/schemas/CloudEventPowerSaving"
          org.camaraproject.iot-network-optimization-notification.v1.power-saving.error: "#/components/schemas/CloudEventError"
    CloudEventPowerSaving:
      description: provides back the power saving operation result.
      allOf:
        - $ref: "#/components/schemas/CloudEvent"
      properties:
        data:
          $ref: "#/components/schemas/PowerSavingResponse"

    CloudEventError:
      description: Error notification for a power saving report request.
      allOf:
        - $ref: "#/components/schemas/CloudEvent"
      properties:
        data:
          allOf:
            - $ref: "#/components/schemas/ErrorInfo"
            - type: object
              properties:
                transactionId:
                  type: string
                  format: uuid
                  description: Transaction identifier allocated for enabling/disabling IoT
                    features
              required:
                - transactionId

    PowerSavingResponse:
      type: object
      properties:
        activationStatus:
          type: array
          items:
            $ref: '#/components/schemas/DeviceStatus'
        transactionId:
          type: string

    DeviceStatus:
      type: object
      properties:
        device:
          $ref: '#/components/schemas/Device'
        status:
          type: string
          enum: [pending, in-progress, success, failed]

    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:
        * `ipv4Address`
        * `ipv6Address`
        * `phoneNumber`
        * `networkAccessIdentifier`
        NOTE1: the MNO might support only a subset of these options.
        The API invoker can provide multiple identifiers to be compatible
        across different MNOs. In this case the identifiers MUST belong to
        the same device.
        NOTE2: as for this Commonalities release, 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"
        ipv4Address:
          $ref: "#/components/schemas/DeviceIpv4Addr"
        ipv6Address:
          $ref: "#/components/schemas/DeviceIpv6Address"
      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"
    DeviceIpv4Addr:
      type: object
      description: |
        The device should be identified by either the public (observed) IP
          address and port as seen by the application server, or the private
          (local) and any public (observed) IP addresses in use by the device
          (this information can be obtained by various means, for example from
          some DNS servers).
        If the allocated and observed IP addresses are the same (i.e. NAT is not
          in use) then  the same address should be specified for both
          publicAddress and privateAddress.
        If NAT64 is in use, the device should be identified by its publicAddress
          and publicPort, or separately by its allocated IPv6 address (field
          ipv6Address of the Device object)
        In all cases, publicAddress must be specified, along with at least one
          of either privateAddress or publicPort, dependent upon which is known.
          In general, mobile devices cannot be identified by their public IPv4
          address alone.
      properties:
        publicAddress:
          $ref: "#/components/schemas/SingleIpv4Addr"
        privateAddress:
          $ref: "#/components/schemas/SingleIpv4Addr"
        publicPort:
          $ref: "#/components/schemas/Port"
      anyOf:
        - required: [publicAddress, privateAddress]
        - required: [publicAddress, publicPort]
      example:
        publicAddress: "84.125.93.10"
        publicPort: 59765
    SingleIpv4Addr:
      description: A single IPv4 address with no subnet mask
      type: string
      format: ipv4
      example: "84.125.93.10"
    Port:
      description: TCP or UDP port number
      type: integer
      minimum: 0
      maximum: 65535
    DeviceIpv6Address:
      description: |
       The device should be identified by the observed IPv6 address, or by any
         single IPv6 address from within the subnet allocated to the device
         (e.g. adding ::0 to the /64 prefix).
      type: string
      format: ipv6
      example: 2001:db8:85a3:8d3:1319:8a2e:370:7344

    TransactionId:
      type: string
      format: uuid
      description: Transaction identifier allocated for enabling/disabling IoT
        features
    XCorrelator:
      type: string
      pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
      example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
    ############################################################################
    #                                 Responses                                #
    ############################################################################
    ErrorInfo:
      description: error information
      type: object
      required:
        - status
        - code
        - message
      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
  responses:
    Generic400:
      description: Bad Request
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 400
                  code:
                    enum:
                      - INVALID_ARGUMENT
                      - OUT_OF_RANGE
          examples:
            GENERIC_400_INVALID_ARGUMENT:
              description: Invalid Argument. Generic Syntax Exception
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or
                  query param.
            GENERIC_400_OUT_OF_RANGE:
              description: Out of Range. Specific Syntax Exception used when a
                given field has has an unsupported value.
              value:
                status: 400
                code: OUT_OF_RANGE
                message: Client specified an invalid range.
    Generic401:
      description: Unauthorized
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 401
                  code:
                    enum:
                      - UNAUTHENTICATED
          examples:
            GENERIC_401_UNAUTHENTICATED:
              description: |
                Request cannot be authenticated and a new authentication is
                required
              value:
                status: 401
                code: UNAUTHENTICATED
                message: |
                  Request not authenticated due to missing, invalid, or expired
                  credentials. A new authentication is required.
    Generic403:
      description: Forbidden
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 403
                  code:
                    enum:
                      - PERMISSION_DENIED
          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.
    Generic404:
      description: Not found
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 404
                  code:
                    enum:
                      - NOT_FOUND
                      - UNKNOWN_APPLICATION_IDENTIFIER
          examples:
            GENERIC_404_NOT_FOUND:
              description: Resource is not found
              value:
                status: 404
                code: NOT_FOUND
                message: The specified resource is not found.
            GENERIC_404_IDENTIFIER_NOT_FOUND:
              description: Application Identifier unknown
              value:
                status: 404
                code: UNKNOWN_APPLICATION_IDENTIFIER
                message: the target application is unknown.
    Generic409:
      description: Conflict
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 409
                  code:
                    enum:
                      - CONFLICT
          examples:
            GENERIC_409_CONFLICT:
              description: Device already in the requested state or conflicting operation in progress
              value:
                status: 409
                code: CONFLICT
                message: The device is already in the requested power-saving state or a conflicting operation is in progress.
    Generic410:
      description: Gone
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 410
                  code:
                    enum:
                      - GONE
          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.
    Generic422:
      description: Unprocessable Content
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 422
                  code:
                    enum:
                      - SERVICE_NOT_APPLICABLE
                      - MISSING_IDENTIFIER
          examples:
            GENERIC_422_SERVICE_NOT_APPLICABLE:
              description: Service not applicable for the provided
                identifier
              value:
                status: 422
                code: SERVICE_NOT_APPLICABLE
                message: The service is not available for the
                  provided identifier.
            GENERIC_422_MISSING_IDENTIFIER:
              description: the Application Identifier is not included in the
                request
              value:
                status: 422
                code: MISSING_IDENTIFIER
                message: unspecified Application Identifier.
    Generic429:
      description: Too Many Requests
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 429
                  code:
                    enum:
                      - QUOTA_EXCEEDED
                      - TOO_MANY_REQUESTS
          examples:
            GENERIC_429_QUOTA_EXCEEDED:
              description: Request is rejected due to exceeding a
                business quota limit
              value:
                status: 429
                code: QUOTA_EXCEEDED
                message: Out of resource quota.
            GENERIC_429_TOO_MANY_REQUESTS:
              description: Access to the API has been temporarily
                blocked due to rate or spike arrest limits being reached
              value:
                status: 429
                code: TOO_MANY_REQUESTS
                message: Rate limit reached.
    Generic501:
      description: Not Implemented
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 501
                  code:
                    enum:
                      - NOT_IMPLEMENTED
          examples:
            GENERIC_501_NOT_IMPLEMENTED:
              description: Service not implemented. The use of this code
                should be avoided as far as possible to get the objective
                to reach aligned implementations
              value:
                status: 501
                code: NOT_IMPLEMENTED
                message: This functionality is not implemented yet.