8.8 Subscription, unsubscription and notifications for the CAPIF events
23.2223GPPCommon API Framework for 3GPP Northbound APIsRelease 18TS
8.8.1 General
The CAPIF core function enables the subscribing entity (i.e. the API invoker, the API exposing function, the API publishing function, the API management function) to subscribe to and unsubscribe from the CAPIF events such as availability events of service APIs, change in service API information, monitoring service API invocations, API invoker onboarding events, etc. The subscription, unsubscription and notification for the CAPIF events are enabled on the following CAPIF reference points:
– CAPIF-1 or CAPIF-1e: the API invoker can subscribe to and unsubscribe from CAPIF events and receive notifications from the CAPIF core function;
– CAPIF-3 or CAPIF-3e: the AEF can subscribe to and unsubscribe from CAPIF events and receive notifications from the CAPIF core function;
– CAPIF-4 or CAPIF-4e: the API publishing function can subscribe to and unsubscribe from CAPIF events and receive notifications from the CAPIF core function; and
– CAPIF-5 or CAPIF-5e: the API management function can subscribe to and unsubscribe from CAPIF events and receive notifications from the CAPIF core function.
NOTE: Support for subscriptions and notifications can also be part of the actual service APIs. That type of subscriptions and notifications is not covered by the provisions in this clause.
8.8.2 Information flows
8.8.2.1 Event subscription request
Table 8.8.2.1-1 describes the information flow for event subscription request from the subscribing entity to the CAPIF core function.
Table 8.8.2.1-1: Event subscription request
|
Information element |
Status |
Description |
|
Identity information |
M |
The information to determine the identity of the subscribing entity |
|
Event criteria |
M |
The event criteria include event type information like failure API invocation event, new API available event, API version change event, API location change event, etc and other query information like service API identifier, service API name, etc. |
|
Notification reception information |
O |
The information of the subscribing entity for receiving the notifications for the event. |
8.8.2.2 Event subscription response
Table 8.8.2.2-1 describes the information flow for event subscription response from the CAPIF core function to the subscribing entity.
Table 8.8.2.2-1: Event subscription response
|
Information element |
Status |
Description |
|
Result |
M |
Indicates the success or failure of the event subscription operation |
|
Subscription identifier |
O (see NOTE) |
The unique identifier for the event subscription. |
|
NOTE: Shall be present if the Result information element indicates that the event subscription operation is successful. Otherwise subscription identifier shall not be present. |
||
8.8.2.3 Event notification
Table 8.8.2.3-1 describes the information flow for event notification from the CAPIF core function to the subscribing entity. A notification about an event is sent to a subscribing entity if the event criteria in the related subscription match the corresponding attributes of the event content.
Table 8.8.2.3-1: Event notification
|
Information element |
Status |
Description |
|
Subscription identifier |
M |
The unique identifier of the event subscription |
|
Event identifier |
M |
The unique identifier for the event. For the list of events, refer subclause 8.8.6 |
|
Event related information |
M |
The event related information (e.g. time at which the event originated, location of event) |
|
Event content |
M |
The content of the event information. |
8.8.2.4 Event notification acknowledgement
Table 8.8.2.4-1 describes the information flow event notification acknowledgement from the subscribing entity to the CAPIF core function.
Table 8.8.2.4-1: Event notification acknowledgement
|
Information element |
Status |
Description |
|
Acknowledgement |
M |
Acknowledgement for the event notification received. |
8.8.2.5 Event unsubscription request
Table 8.8.2.5-1 describes the information flow for event unsubscription request from the subscribing entity to the CAPIF core function.
Table 8.8.2.5-1: Event unsubscription request
|
Information element |
Status |
Description |
|
Identity information |
M |
The information to determine the identity of the subscribing entity |
|
Subscription identifier |
M |
The unique identifier for the event subscription that was provided to the subscribing entity during the CAPIF event subscription operation. |
8.8.2.6 Event unsubscription response
Table 8.8.2.6-1 describes the information flow for event unsubscription response from the CAPIF core function to the subscribing entity.
Table 8.8.2.6-1: Event unsubscription response
|
Information element |
Status |
Description |
|
Result |
M |
Indicates the success or failure of the event unsubscription operation |
8.8.3 Procedure for CAPIF event subscription
Figure 8.8.3-1 illustrates the procedure for CAPIF events subscription.
Pre-conditions:
1. The subscribing entity has the authorization to subscribe for the CAPIF events.
Figure 8.8.3-1: Procedure for CAPIF event subscription
1. The subscribing entity sends an event subscription request to the CAPIF core function in order to receive notification of events.
2. Upon receiving the event subscription request from the subscribing entity, the CAPIF core function checks for the relevant authorization for the event subscription.
3. If the authorization is successful, the CAPIF core function stores the subscription information.
4. The CAPIF core function sends an event subscription response indicating successful operation.
8.8.4 Procedure for CAPIF event notifications
Figure 8.8.4-1 illustrates the procedure for CAPIF event notifications.
Pre-conditions:
1. The subscription procedure as illustrated in figure 8.8.3-1 is performed by the subscribing entity.
Figure 8.8.4-1: Procedure for CAPIF event notifications
1. The CAPIF core function generates events to be consumed by the subscribing entity(s).
2. For the generated event, the CAPIF core function retrieves the list of corresponding subscriptions.
3. The CAPIF core function sends event notifications to all the subscribing entity(s) that have subscribed for the event matching the criteria. If a notification reception information is available as part of the subscribing entity event subscription, then the notification reception information is used by the CAPIF core function to send event notifications to the subscribing entity.
4. The subscribing entity sends an event notification acknowledgement to the CAPIF core function for the event notification received.
8.8.5 Procedure for CAPIF event unsubscription
Figure 8.8.5-1 illustrates the procedure for CAPIF event unsubscription.
Pre-condition:
1. The subscribing entity has subscribed to the CAPIF events.
Figure 8.8.5-1: Procedure for CAPIF event unsubscription
1. The subscribing entity sends an event unsubscription request to the CAPIF core function with the information of the subscribed CAPIF event.
2. Upon receiving the event unsubscription request from the subscribing entity, the CAPIF core function checks for the event subscription corresponding to the subscribing entity and further checks if the subscribing entity is authorized to unsubscribe from the CAPIF event.
3. If the event subscription information corresponding to the subscribing entity is available and the subscribing entity is authorized to unsubscribe for the CAPIF event, the CAPIF core function removes the subscription information.
4. The CAPIF core function sends an event unsubscription response indicating successful operation.
8.8.6 List of CAPIF events
Table 8.8.6-1 provides a non-exhaustive list of CAPIF events.
Table 8.8.6-1: List of CAPIF events
|
Events |
Events Description |
|
Availability of service APIs |
Availability events of service APIs (e.g. active, inactive) |
|
Service API updated |
Events related to change in service API information |
|
Monitoring service API invocations |
Events corresponding to service API invocations |
|
API invoker status |
Events related to API invoker status in CAPIF (onboarded, offboarded) |
|
API topology hiding status |
Events related to API topology hiding status in CAPIF (created, revoked) |
|
System related events |
Alarm events providing fault information |
|
Performance related events |
Events related to system load conditions |