TS29222_CAPIF_Events_API.yaml

openapi: 3.0.0

info:
  title: CAPIF_Events_API
  description: |
    API for event subscription management.  
    © 2023, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.
  version: "1.3.0-alpha.4"

externalDocs:
  description: 3GPP TS 29.222 V18.4.0 Common API Framework for 3GPP Northbound APIs
  url: https://www.3gpp.org/ftp/Specs/archive/29_series/29.222/

servers:
  - url: '{apiRoot}/capif-events/v1'
    variables:
      apiRoot:
        default: https://example.com
        description: apiRoot as defined in clause 7.5 of 3GPP TS 29.222

paths:
  /{subscriberId}/subscriptions:
    post:
      description: Creates a new individual CAPIF Event Subscription.
      parameters:
        - name: subscriberId
          in: path
          description: Identifier of the Subscriber
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventSubscription'
      callbacks:
        notificationDestination:
          '{request.body#/notificationDestination}':
            post:
              requestBody:  # contents of the callback message
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/EventNotification'
              responses:
                '204':
                  description: No Content (successful notification)
                '307':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/307'
                '308':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/308'
                '400':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/400'
                '401':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/401'
                '403':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/403'
                '404':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/404'
                '411':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/411'
                '413':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/413'
                '415':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/415'
                '429':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/429'
                '500':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/500'
                '503':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/503'
                default:
                  $ref: 'TS29122_CommonData.yaml#/components/responses/default'
      responses:
        '201':
          description: Created (Successful creation of subscription)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSubscription'
          headers:
            Location:
              description: >
                Contains the URI of the newly created resource, according to the structure
                {apiRoot}/capif-events/v1/{subscriberId}/subscriptions/{subscriptionId}
              required: true
              schema:
                type: string
        '400':
          $ref: 'TS29122_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29122_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29122_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29122_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29122_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29122_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29122_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29122_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29122_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29122_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

  /{subscriberId}/subscriptions/{subscriptionId}:
    delete:
      description: Deletes an individual CAPIF Event Subscription.
      parameters:
        - name: subscriberId
          in: path
          description: Identifier of the Subscriber
          required: true
          schema:
            type: string
        - name: subscriptionId
          in: path
          description: Identifier of an individual Events Subscription
          required: true
          schema:
            type: string
      responses:
        '204':
          description: >
            The individual CAPIF Events Subscription matching the subscriptionId is deleted.
        '307':
          $ref: 'TS29122_CommonData.yaml#/components/responses/307'
        '308':
          $ref: 'TS29122_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29122_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29122_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29122_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29122_CommonData.yaml#/components/responses/404'
        '429':
          $ref: 'TS29122_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29122_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29122_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

    put:
      description: Update of an existing individual CAPIF Event Subscription.
      parameters:
        - name: subscriberId
          in: path
          description: Identifier of the Subscriber
          required: true
          schema:
            type: string
        - name: subscriptionId
          in: path
          description: Identifier of the individual Subscriber
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventSubscription'
      responses:
        '200':
          description: OK (Successful update of the subscription).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSubscription'
        '204':
          description: No Content
        '400':
          $ref: 'TS29122_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29122_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29122_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29122_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29122_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29122_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29122_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29122_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29122_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29122_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

    patch:
      description: Modification of an existing individual CAPIF Event Subscription.
      parameters:
        - name: subscriberId
          in: path
          description: Identifier of the Subscriber
          required: true
          schema:
            type: string
        - name: subscriptionId
          in: path
          description: Identifier of the individual Subscriber
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/EventSubscriptionPatch'
      responses:
        '200':
          description: OK (Successful update of the subscription)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSubscription'
        '204':
          description: No Content
        '400':
          $ref: 'TS29122_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29122_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29122_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29122_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29122_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29122_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29122_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29122_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29122_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29122_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

components:
  schemas:
    EventSubscription:
      type: object
      description: Represents an individual CAPIF Event Subscription resource.
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/CAPIFEvent'
          minItems: 1
          description: Subscribed events
        eventFilters:
          type: array
          items:
            $ref: '#/components/schemas/CAPIFEventFilter'
          minItems: 1
          description: Subscribed event filters
        eventReq:
          $ref: 'TS29523_Npcf_EventExposure.yaml#/components/schemas/ReportingInformation'
        notificationDestination:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'
        requestTestNotification:
          type: boolean
          description: >
            Set to true by Subscriber to request the CAPIF core function to send a
            test notification as defined in in clause 7.6. Set to false or omitted otherwise.
        websockNotifConfig:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/WebsockNotifConfig'
        supportedFeatures:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      required:
        - events
        - notificationDestination

    EventNotification:
      type: object
      description: Represents an individual CAPIF Event notification.
      properties:
        subscriptionId:
          type: string
          description: >
            Identifier of the subscription resource to which the notification
            is related – CAPIF resource identifier
        events:
          $ref: '#/components/schemas/CAPIFEvent'
        eventDetail:
          $ref: '#/components/schemas/CAPIFEventDetail'
      required:
        - subscriptionId
        - events

    CAPIFEventFilter:
      type: object
      description: Represents a CAPIF event filter.
      properties:
        apiIds:
          type: array
          items:
            type: string
          minItems: 1
          description: Identifier of the service API
        apiInvokerIds:
          type: array
          items:
            type: string
          minItems: 1
          description: Identity of the API invoker
        aefIds:
          type: array
          items:
            type: string
          minItems: 1
          description: Identifier of the API exposing function

    CAPIFEventDetail:
      type: object
      description: Represents a CAPIF event details.
      properties:
        serviceAPIDescriptions:
          type: array
          items:
            $ref: 'TS29222_CAPIF_Publish_Service_API.yaml#/components/schemas/ServiceAPIDescription'
          minItems: 1
          description: Description of the service API as published by the APF.
        apiIds:
          type: array
          items:
            type: string
          minItems: 1
          description: Identifier of the service API
        apiInvokerIds:
          type: array
          items:
            type: string
          minItems: 1
          description: Identity of the API invoker
        accCtrlPolList:
          $ref: '#/components/schemas/AccessControlPolicyListExt'
        invocationLogs:
          type: array
          items:
            $ref: 'TS29222_CAPIF_Logging_API_Invocation_API.yaml#/components/schemas/InvocationLog'
          minItems: 1
          description: Invocation logs.
        apiTopoHide:
          $ref: '#/components/schemas/TopologyHiding'

    AccessControlPolicyListExt:
      description: Represents the extension for access control policies.
      allOf:
        - $ref: 'TS29222_CAPIF_Access_Control_Policy_API.yaml#/components/schemas/AccessControlPolicyList'
        - type: object
          properties:
            apiId:
              type: string
      required:
        - apiId

    TopologyHiding:
      type: object
      description: Represents the routing rules information of a service API.
      properties:
        apiId:
          type: string
        routingRules:
          type: array
          items:
            $ref: 'TS29222_CAPIF_Routing_Info_API.yaml#/components/schemas/RoutingRule'
          minItems: 1
      required:
        - apiId
        - routingRules

    EventSubscriptionPatch:
      type: object
      description: >
        Represents the parameters to request the updated of an individual CAPIF Event
        Subscription resource.
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/CAPIFEvent'
          minItems: 1
          description: Subscribed events
        eventFilters:
          type: array
          items:
            $ref: '#/components/schemas/CAPIFEventFilter'
          minItems: 1
          description: Subscribed event filters
        eventReq:
          $ref: 'TS29523_Npcf_EventExposure.yaml#/components/schemas/ReportingInformation'
        notificationDestination:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'

    CAPIFEvent:
      anyOf:
      - type: string
        enum:
          - SERVICE_API_AVAILABLE
          - SERVICE_API_UNAVAILABLE
          - SERVICE_API_UPDATE
          - API_INVOKER_ONBOARDED
          - API_INVOKER_OFFBOARDED
          - SERVICE_API_INVOCATION_SUCCESS
          - SERVICE_API_INVOCATION_FAILURE
          - ACCESS_CONTROL_POLICY_UPDATE
          - ACCESS_CONTROL_POLICY_UNAVAILABLE
          - API_INVOKER_AUTHORIZATION_REVOKED
          - API_INVOKER_UPDATED
          - API_TOPOLOGY_HIDING_CREATED
          - API_TOPOLOGY_HIDING_REVOKED
      - type: string
        description: >
          This string provides forward-compatibility with future
          extensions to the enumeration but is not used to encode
          content defined in the present version of this API.
      description: |
        Describes the CAPIF event.  
        Possible values are:
        - SERVICE_API_AVAILABLE:
          Events related to the availability of service APIs after the service APIs are
          published.
        - SERVICE_API_UNAVAILABLE:
          Events related to the unavailability of service APIs after the service APIs are
          unpublished.
        - SERVICE_API_UPDATE: Events related to change in service API information.
        - API_INVOKER_ONBOARDED: Events related to API invoker onboarded to CAPIF.
        - API_INVOKER_OFFBOARDED: Events related to API invoker offboarded from CAPIF.
        - SERVICE_API_INVOCATION_SUCCESS:
          Events related to the successful invocation of service APIs.
        - SERVICE_API_INVOCATION_FAILURE: Events related to the failed invocation of service APIs.
        - ACCESS_CONTROL_POLICY_UPDATE:
          Events related to the update for the access control policy related to the service APIs.
        - ACCESS_CONTROL_POLICY_UNAVAILABLE:
          Events related to the unavailability of the access control policy related to
          the service APIs.
        - API_INVOKER_AUTHORIZATION_REVOKED: Events related to the revocation of the authorization
          of API invokers to access the service APIs.
        - API_INVOKER_UPDATED: Events related to API invoker profile updated to CAPIF.
        - API_TOPOLOGY_HIDING_CREATED:
          Events related to the creation or update of the API topology hiding
          information of the service APIs after the service APIs are published.
        - API_TOPOLOGY_HIDING_REVOKED:
          Events related to the revocation of the API topology hiding information of
          the service APIs after the service APIs are unpublished.