TS29551_Nnef_PFDmanagement.yaml

openapi: 3.0.0
info:
  title: Nnef_PFDmanagement Service API
  version: 1.3.0-alpha.3
  description: |
    Packet Flow Description Management Service.  
    © 2024, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.
#
externalDocs:
  description: 3GPP TS 29.551 v18.4.0, 5G System; Packet Flow Description Management Service
  url: 'https://www.3gpp.org/ftp/Specs/archive/29_series/29.551/'
#
servers:
  - url: '{apiRoot}/nnef-pfdmanagement/v1'
    variables:
      apiRoot:
        default: https://example.com
        description: apiRoot as defined in clause 4.4 of 3GPP TS 29.501
security:
  - {}
  - oAuth2ClientCredentials:
    - nnef-pfdmanagement
paths:
  /applications:
    get:
      summary: Retrieve PFDs for all applications or for one or multiple applications with query parameter.
      tags:
        - PFD of applications
      operationId: Nnef_PFDmanagement_AllFetch
      parameters:
          - name: application-ids
            description: The required application identifier(s) for the returned PFDs.
            in: query
            required: true
            schema:
              type: array
              items:
                $ref: 'TS29571_CommonData.yaml#/components/schemas/ApplicationId'
              minItems: 1
          - name: supported-features
            in: query
            description: To filter irrelevant responses related to unsupported features
            schema:
               $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      responses:
        '200':
          description: >
            The PFDs for one or more application identifier(s) in the request URI are returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PfdDataForApp'
                minItems: 0
        '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'
        '406':
          $ref: 'TS29571_CommonData.yaml#/components/responses/406'
        '414':
          $ref: 'TS29571_CommonData.yaml#/components/responses/414'
        '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'

  /applications/partialpull:
    post:
      summary: retrieve the PFD(s) by partial update
      operationId: Nnef_PFDmanagement_AppFetchPartialUpdate
      tags:
        - PFD of applications by partial update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ApplicationForPfdRequest'
              minItems: 1
      responses:
        '200':
          description: OK. Changed PFD(s) is returned
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PfdDataForApp'
                minItems: 1
        '204':
          description: The PFD(s) is not changed
        '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'

  /applications/{appId}:
    get:
      summary: Retrieve the PFD for an application.
      tags:
        - Individual application PFD
      operationId: Nnef_PFDmanagement_IndAppFetch
      parameters:
        - name: appId
          description: The required application identifier(s) for the returned PFDs.
          in: path
          required: true
          schema:
            type: string
        - name: supported-features
          in: query
          description: To filter irrelevant responses related to unsupported features
          schema:
             $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      responses:
        '200':
          description: A representation of PFDs for an application in the request URI is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PfdDataForApp'
        '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'
        '406':
          $ref: 'TS29571_CommonData.yaml#/components/responses/406'
        '429':
          $ref: 'TS29571_CommonData.yaml#/components/responses/429'
        '414':
          $ref: 'TS29571_CommonData.yaml#/components/responses/414'
        '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:
    post:
      summary: Subscribe the notification of PFD changes.
      tags:
        - PFD subscriptions
      operationId: Nnef_PFDmanagement_CreateSubscr
      requestBody:
        description: a PfdSubscription resource to be created.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PfdSubscription'
      callbacks:
        PfdChangeNotification:
          '{request.body#/notifyUri}':
            post:
              summary: Notification of PFD change.
              tags:
                - PfdChangeNotification data
              operationId: Nnef_PFDmanagement_Notify
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      type: array
                      items:
                        $ref: '#/components/schemas/PfdChangeNotification'
                      minItems: 1
              responses:
                '200':
                  description: >
                    The PFD operation in the notification is performed and the
                    PfdChangeReport indicates failure reason.
                  content:
                    application/json:
                      schema:
                        type: array
                        items:
                          $ref: '#/components/schemas/PfdChangeReport'
                        minItems: 1
                '204':
                  description: The PFD operation in the notification is performed successfully.
                '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'

        NotificationPush:
          '{request.body#/notifyUri}/notifypush':
            post:
              summary: Notification Push.
              tags:
                - NotificationPush data
              operationId: Nnef_PFDmanagement_PushNotify
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      type: array
                      items:
                        $ref: '#/components/schemas/NotificationPush'
                      minItems: 1
              responses:
                '204':
                  description: Notificaiton PUSH is accepted.
                '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'

      responses:
        '201':
          description: >
            The creation of a PfdSubscription resource is confirmed and a representation of
            that resource is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PfdSubscription'
          headers:
            Location:
              description: >
                Contains the URI of the newly created resource, according to the structure
                {apiRoot}/nnef-pfdmanagement/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'

  /subscriptions/{subscriptionId}:
    put:
      summary: Updates/replaces an existing subscription resource
      tags:
        - Individual PFD subscription
      operationId: Nnef_PFDmanagement_ModifySubscr
      parameters:
        - name: subscriptionId
          description: Identify the subscription.
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: Parameters to update/replace the existing subscription
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PfdSubscription'
      responses:
        '200':
          description: OK (Successful update of the subscription)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PfdSubscription'
        '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:
      summary: Delete a subscription of PFD change notification.
      tags:
        - Individual PFD subscription
      operationId: Nnef_PFDmanagement_Unsubscribe
      parameters:
        - name: subscriptionId
          description: Identify the subscription.
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: >
            The PfdSubscription resource matching the subscriptionId was deleted successfully.
        '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:
            nnef-pfdmanagement: Access to the Nnef_PFDmanagement API
  schemas:
#
# STRUCTURED DATA TYPES
#
    PfdContent:
      description: Represents the content of a PFD for an application identifier.
      type: object
      properties:
        pfdId:
          type: string
          description: Identifies a PDF of an application identifier.
        flowDescriptions:
          type: array
          items:
            type: string
          minItems: 1
          description: >
            Represents a 3-tuple with protocol, server ip and server port for UL/DL
            application traffic.
        urls:
          type: array
          items:
            type: string
          minItems: 1
          description: >
            Indicates a URL or a regular expression which is used to match the significant parts
            of the URL.
        domainNames:
          type: array
          items:
            type: string
          minItems: 1
          description: Indicates an FQDN or a regular expression as a domain name matching criteria.
        dnProtocol:
          $ref: 'TS29122_PfdManagement.yaml#/components/schemas/DomainNameProtocol'
        sourceNfType:
          $ref: 'TS29510_Nnrf_NFManagement.yaml#/components/schemas/NFType'

    PfdDataForApp:
      description: Represents the PFDs for an application identifier.
      type: object
      properties:
        applicationId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/ApplicationId'
        pfds:
          type: array
          items:
            $ref: '#/components/schemas/PfdContent'
          minItems: 1
        cachingTime:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DateTime'
        cachingTimer:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DurationSec'
        pfdTimestamp:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DateTime'
        partialFlag:
          type: boolean
          description: >
            Indication of partial update of PFDs for an existing application identifier if it is 
            included and set to true. Otherwise set to false indicates not supporting partial 
            update of PFDs for an existing application identifier. The default value false 
            applies if the attribute is not present.
          default: false
        supportedFeatures:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      required:
        - applicationId

    PfdSubscription:
      description: Represents a PFD subscription.
      type: object
      properties:
        applicationIds:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/ApplicationId'
          minItems: 1
        notifyUri:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
        supportedFeatures:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      required:
        - notifyUri
        - supportedFeatures

    PfdChangeNotification:
      description: Represents information related to a notification of PFD change.
      type: object
      properties:
        applicationId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/ApplicationId'
        removalFlag:
          type: boolean
          description: >
            Indication of removal of PFDs for an existing application identifier.
            Set to true indicates the PFDs are removed.
            Set to false indicates the PFDs are not removed.
            Default value is false if omitted.
          default: false
        partialFlag:
          type: boolean
          description: >
            Indication of partial update of PFDs for an existing application identifier 
            if this operation is supported according to feature negotiation.
            Set to true indicates partial update PFDs for the included application identifier.
            Set to false indicates not partial update PFDs for the included application identifier.
            Default value is "false" if omitted.
          default: false
        pfds:
          type: array
          items:
            $ref: '#/components/schemas/PfdContent'
          minItems: 1
      required:
        - applicationId

    NotificationPush:
      description: >
        Represents the information to be used by the NF service consumer to retrieve the
        PFDs and/or remove the PFDs of the applicable application identifier(s).
      type: object
      properties:
        appIds:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/ApplicationId'
          minItems: 1
        allowedDelay:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DurationSec'
        pfdOp:
          $ref: '#/components/schemas/PfdOperation'
      required:
        - appIds

    PfdChangeReport:
      description: Represents an error report on PFD change.
      type: object
      properties:
        pfdError:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/ProblemDetails'
        applicationId:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/ApplicationId'
          minItems: 1
      required:
        - pfdError
        - applicationId

    ApplicationForPfdRequest:
      description: Contains the application identifier(s) for the PFD(s) request.
      type: object
      properties:
        applicationId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/ApplicationId'
        pfdTimestamp:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DateTime'
      required:
        - applicationId

#
# ENUMERATIONS
#
    PfdOperation:
      description: Indicates the operation to be applied on PFD(s).
      anyOf:
      - type: string
        enum:
          - RETRIEVE
          - FULLPULL
          - PARTIALPULL
          - REMOVE
      - 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.