Tech-invite  3GPPspecsRELsGlossariesSIP
Info21222324252627282931323334353637384‑5x

full Contents for  TS 23.222  Word version:   17.0.0

Top   Up   Prev   Next
0…   4…   5   6…   6.3…   7…   8…   8.5…   8.9…   8.13…   8.17…   8.21…   8.25…   9…   10…   11…   A   B…   B.2   B.3   C…   D…

 

8.5  Retrieve service APIs
8.5.1  General
The CAPIF supports retrieving the published service APIs information by the API provider. The API publishing function can be within PLMN trust domain or within 3rd party trust domain.
8.5.2  Information flowsWord-p. 42
8.5.2.1  Service API get request
Table 8.5.2.1-1 describes the information flow service API get request from the API publishing function to the CAPIF core function.
Information element
Status
Description

API publisher information
M
The information of the API publisher may include identity, authentication and authorization information
Service API published information reference
M
The information provided by the CAPIF core function which can be for referencing the information (set) about the published service API by the API publishing function.

8.5.2.2  Service API get response
Table 8.5.2.2-1 describes the information flow service API get response from the CAPIF core function to the API publishing function.
Information element
Status
Description

Result
M
Indicates the success or failure of retrieving the service API information
Service API information
O (see NOTE)
The service API information includes the service API name, service API type, communication type, description, Serving Area Information (optional), interface details (e.g. IP address, port number, URI), protocols, version numbers, and data format.

NOTE:
Shall be present if the Result information element indicates that the service API get request is successful. Otherwise service API information shall not be present.

Up
8.5.3  Procedure
Figure 8.5.3-1 illustrates the procedure for retrieving the service APIs. The service API retrieval mechanism is supported by the CAPIF core function.
Pre-condition:
  1. Authorization details of the APF are available with the CAPIF core function.
Up
  1. The API publishing function sends a service API get request to the CAPIF core function, with service API published information reference provided by the CAPIF core function when the service API was published.
  2. Upon receiving the service API get request, the CAPIF core function checks whether the API publishing function is authorized to get published service APIs information. If the check is successful, the corresponding service API information is retrieved from the CAPIF core function (API registry).
  3. The CAPIF core function provides a service API get response to the API publishing function which includes the service API information.
Up
8.6  Update service APIsWord-p. 43
8.6.1  General
The CAPIF core function allows the service API provider to update the information related to the published service API, e.g. a change in the characteristics of the service API. This procedure is initiated by the API publishing function to the CAPIF core function. The API publishing function can be within PLMN trust domain or within 3rd party trust domain.
8.6.2  Information flows
8.6.2.1  Service API update request
Table 8.6.2.1-1 describes the information flow service API update request from the API publishing function to the CAPIF core function.
Information element
Status
Description

API publisher information
M
The information of the API publisher may include identity, authentication and authorization information
Service API published information reference
M
The information (set) provided by the CAPIF core function about the published service API which can be used for reference by the API publishing function.
Service API information
M
The service API information includes the service API name, service API type, communication type, description, Serving Area Information (optional), interface details (e.g. IP address, port number, URI), protocols, version numbers, and data format which is required to replace the existing service API information
Reason
O
The reason of the update (e.g. change log)

Up
8.6.2.2  Service API update response
Table 8.6.2.2-1 describes the information flow service API update response from the CAPIF core function to the API publishing function.
Information element
Status
Description

Result
M
Indicates the success or failure of updating the service API information

8.6.3  ProcedureWord-p. 44
Figure 8.6.3-1 illustrates the procedure for updating the published service APIs information. The service API update mechanism is supported by the CAPIF core function.
Pre-conditions:
  1. Authorization details of the APF are available with the CAPIF core function.
  2. API invokers may have subscribed with the CAPIF core function to obtain notification regarding update to service API information.
Up
  1. The API publishing function sends a service API update request to the CAPIF core function, which includes the service API published information reference provided by the CAPIF core function when the service API was published and the new service API information which is to be updated.
  2. Upon receiving the service API update request, the CAPIF core function checks whether the API publishing function is authorized to update the published service APIs information. If the check is successful, the service API information provided by the API publishing function is updated at the CAPIF core function (API registry).
  3. The CAPIF core function provides a service API update response to the API publishing function and triggers notifications to subscribed API invokers as described in subclause 8.8.4.
Up
8.7  Discover service APIs
8.7.1  General
The following procedure in this subclause corresponds to the architectural requirements on discover service APIs.
8.7.2  Information flows
8.7.2.1  Service API discover request
Table 8.7.2.1-1 describes the information flow service API discover request from the API invoker to the CAPIF core function.
Information element
Status
Description

API invoker identity information
M
Identity information of the API invoker discovering service APIs
Query information
M
Criteria for discovering matching service APIs (e.g. service API type, Serving Area Information (optional), interfaces, protocols) (see NOTE)

NOTE:
It should be possible to discover all the service APIs.

8.7.2.2  Service API discover responseWord-p. 45
Table 8.7.2.2-1 describes the information flow service API discover response from the CAPIF core function to the API invoker.
Information element
Status
Description

Result
M
Indicates the success or failure of the discovery of the service API information
Service API information (see NOTE 2)
O (see NOTE 1)
List of service APIs corresponding to the request, including API description such as service API name, service API type, Serving Area Information (optional), interface details (e.g. IP address, port number, URI), protocols, version, data format
CAPIF core function identity information
O (see NOTE 1)
Indicates the CAPIF core function serving the service API category provided in the query criteria

NOTE 1:
The service API information or the CAPIF core function identity information or both shall be present if the Result information element indicates that the service API discover operation is successful. Otherwise both shall not be present.
NOTE 2:
If topology hiding is enabled for the service API, the interface details shall be the interface details of AEF acting as service communication entry point for the service API.

Up
8.7.3  Procedure
Figure 8.7.3-1 illustrates the procedure for discover service APIs.
The service API discovery mechanism is supported by the CAPIF core function.
Pre-conditions:
  1. The API invoker is onboarded and has received an API invoker identity.
  2. The CAPIF core function is configured with a discovery policy information (e.g. to restrict discovery to category of APIs) for API invoker(s).
Up
  1. The API invoker sends a service API discover request to the CAPIF core function. It includes the API invoker identity, and may include query information.
  2. Upon receiving the service API discover request, the CAPIF core function verifies the identity of the API invoker (via authentication). The CAPIF core function retrieves the stored service API(s) information from the CAPIF core function (API registry) as per the query information in the service API discover request. Further, the CAPIF core function applies the discovery policy and performs filtering of service APIs information retrieved from the CAPIF core function.
  3. The CAPIF core function sends a service API discover response to the API invoker with the list of service API information for which the API invoker has the required authorization.
Up
8.8  Subscription, unsubscription and notifications for the CAPIF eventsWord-p. 46
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.
Up
8.8.2  Information flowsWord-p. 47
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.
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.

Up
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.
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.
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.

Up
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.
Information element
Status
Description

Acknowledgement
M
Acknowledgement for the event notification received.

8.8.2.5  Event unsubscription requestWord-p. 48
Table 8.8.2.5-1 describes the information flow for event unsubscription request from the subscribing entity to the CAPIF core function.
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.
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.
Up
  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 notificationsWord-p. 49
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.
Up
  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.
Up
8.8.5  Procedure for CAPIF event unsubscriptionWord-p. 50
Figure 8.8.5-1 illustrates the procedure for CAPIF event unsubscription.
Pre-condition:
  1. The subscribing entity has subscribed to the CAPIF events.
Up
  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.
Up
8.8.6  List of CAPIF events
Table 8.8.6-1 provides a non-exhaustive 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)
System related events
Alarm events providing fault information
Performance related events
Events related to system load conditions

Up

Up   Top   ToC