TS29594_Nchf_SpendingLimitControl.yaml

openapi: 3.0.0

info:
  version: 1.3.0-alpha.2
  title: Nchf_SpendingLimitControl
  description: |
    Nchf Spending Limit Control Service.  
    © 2023, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.

externalDocs:
  description: 3GPP TS 29.594 V18.3.0; 5G System; Spending Limit Control Service.
  url: 'https://www.3gpp.org/ftp/Specs/archive/29_series/29.594/'

servers:
  - url: '{apiRoot}/nchf-spendinglimitcontrol/v1'
    variables:
      apiRoot:
        default: https://example.com
        description: apiRoot as defined in clause 4.4 of 3GPP TS 29.501

security:
  - {}
  - oAuth2ClientCredentials:
    - nchf-spendinglimitcontrol

paths:

  /subscriptions:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpendingLimitContext'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpendingLimitStatus'
          headers:
            Location:
              description: >
                Contains the URI of the created individual spending limit resource,
                according to the structure
                {apiRoot}/nchf-spendinglimitcontrol/v1/subscriptions/{subscriptionId}
              required: true
              schema:
                type: string
        '400':
          $ref: 'TS29571_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29571_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29571_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29571_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29571_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29571_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29571_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29571_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29571_CommonData.yaml#/components/responses/500'
        '502':
          $ref: 'TS29571_CommonData.yaml#/components/responses/502'
        '503':
          $ref: 'TS29571_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29571_CommonData.yaml#/components/responses/default'
      callbacks:
        statusNotification:
          '{$request.body#/notifUri}/notify': 
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/SpendingLimitStatus'
              responses:
                '204':
                  description: No Content, Notification was succesfull
                '307': 
                  $ref: 'TS29571_CommonData.yaml#/components/responses/307'
                '308': 
                  $ref: 'TS29571_CommonData.yaml#/components/responses/308'
                '400':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/400'
                '401':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/401'
                '403':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/403'
                '404':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/404'
                '411':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/411'
                '413':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/413'
                '415':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/415'
                '429':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/429'
                '500':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/500'
                '502':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/502'
                '503':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/503'
                default:
                  $ref: 'TS29571_CommonData.yaml#/components/responses/default'
        subscriptionTermination:
          '{$request.body#/notifUri}/terminate': 
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/SubscriptionTerminationInfo'
              responses:
                '204':
                  description: No Content, Notification was succesfull
                '307': 
                  $ref: 'TS29571_CommonData.yaml#/components/responses/307'
                '308': 
                  $ref: 'TS29571_CommonData.yaml#/components/responses/308'
                '400':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/400'
                '401':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/401'
                '403':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/403'
                '404':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/404'
                '411':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/411'
                '413':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/413'
                '415':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/415'
                '429':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/429'
                '500':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/500'
                '502':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/502'
                '503':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/503'
                default:
                  $ref: 'TS29571_CommonData.yaml#/components/responses/default'

  /subscriptions/{subscriptionId}:
    parameters:
      - in: path
        name: subscriptionId
        description: Identifies an individual spending limit retrieval subscription.
        required: true
        schema:
          type: string
    put:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpendingLimitContext'
      responses:
        '200':
          description: OK. Resource was succesfully modified and representation is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpendingLimitStatus'
        '307': 
          $ref: 'TS29571_CommonData.yaml#/components/responses/307'
        '308': 
          $ref: 'TS29571_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29571_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29571_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29571_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29571_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29571_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29571_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29571_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29571_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29571_CommonData.yaml#/components/responses/500'
        '502':
          $ref: 'TS29571_CommonData.yaml#/components/responses/502'
        '503':
          $ref: 'TS29571_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29571_CommonData.yaml#/components/responses/default'
    delete:
      responses:
        '204':
          description: No Content. Resource was succesfully deleted
        '307': 
          $ref: 'TS29571_CommonData.yaml#/components/responses/307'
        '308': 
          $ref: 'TS29571_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29571_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29571_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29571_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29571_CommonData.yaml#/components/responses/404'
        '429':
          $ref: 'TS29571_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29571_CommonData.yaml#/components/responses/500'
        '502':
          $ref: 'TS29571_CommonData.yaml#/components/responses/502'
        '503':
          $ref: 'TS29571_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29571_CommonData.yaml#/components/responses/default'


components:
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '{nrfApiRoot}/oauth2/token'
          scopes:
            nchf-spendinglimitcontrol: Access to the Nchf_SpendingLimitControl API

  schemas:
    SpendingLimitContext:
      description: >
        Represents the subscription data structure required for an individual CHF spending limit
        subscription.
      type: object
      properties:
        supi:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Supi'
        gpsi:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Gpsi'
        policyCounterIds:
          type: array
          items:
            $ref: '#/components/schemas/PolicyCounterId'
          minItems: 1
          description: >
            This is a list of policy counter identifier(s), which identifies policy counters
            maintained per subscriber within the CHF.
        notifUri:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
        expiry:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DateTime'
        supportedFeatures:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
        notifId:
          type: string

    SpendingLimitStatus:
      description: >
        Represents the data structure presenting the statuses of policy counters.
      type: object
      properties:
        supi:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Supi'
        notifId:
          type: string
        statusInfos:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PolicyCounterInfo'
          minProperties: 1
          description: >
            Status of the requested policy counters. The key of the map is the attribute
            "policyCounterId".
        expiry:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DateTime'
        supportedFeatures:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'

    PolicyCounterInfo:
      description: Represents the data structure presenting the policy counter status.
      type: object
      properties:
        policyCounterId:
          $ref: '#/components/schemas/PolicyCounterId'
        currentStatus:
          type: string
          description: >
            Identifies the policy counter status applicable for a specific policy counter identified
            by the policyCounterId. The values (e.g. valid, invalid or any other status) are not
            specified. The interpretation and actions related to the defined values are out of scope
            of 3GPP.
        penPolCounterStatuses:
          type: array
          items:
            $ref: '#/components/schemas/PendingPolicyCounterStatus'
          minItems: 1
          description: Provides the pending policy counter status.
      required:
        - policyCounterId
        - currentStatus

    PendingPolicyCounterStatus:
      description: >
        Represents the data structure presenting the pending policy counter status.
      type: object
      properties:
        policyCounterStatus:
          type: string
          description: >
            Identifies the policy counter status applicable for a specific policy counter identified
            by the policyCounterId. The values (e.g. valid, invalid or any other status) are not
            specified. The interpretation and actions related to the defined values are out of scope
            of 3GPP.
        activationTime:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DateTime'
      required:
        - policyCounterStatus
        - activationTime

    PolicyCounterId:
      type: string
      description: Identifies a policy counter.
    SubscriptionTerminationInfo:
      description: >
        Represents the data structure presenting the indication of the termination of the 
        subscription.
      type: object
      properties:
        supi:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Supi'
        notifId:
          type: string
        termCause:
          $ref: '#/components/schemas/TerminationCause'
      required:
        - supi

# Simple data types and Enumerations 

    TerminationCause:
      anyOf:
      - type: string
        enum:
          - REMOVED_SUBSCRIBER
      - type: string
        description: >
          This string provides forward-compatibility with future extensions to the enumeration
          and is not used to encode content defined in the present version of this API.
      description: |
        Represents the cause for requesting the termination of the subscription to policy counter
        status changes.  
        Possible values are:
        - REMOVED_SUBSCRIBER: The subscriber identified by the SUPI has been removed from the CHF.