Content for TS 23.222 Word version: 19.5.0

0… 4… 5… 6… 6.3… 6.4… 7… 8… 8.5… 8.8… 8.9… 8.13… 8.17… 8.21… 8.25… 8.26… 8.28… 8.30… 8.33… 8.36… 9… 10… 10.4… 10.7… 11… A B… B.2… B.3… C… D…

8.5 Retrieve service APIs 8.5.1 General 8.5.2 Information flows 8.5.2.1 Service API get request 8.5.2.2 Service API get response 8.5.3 Procedure 8.6 Update service APIs 8.6.1 General 8.6.2 Information flows 8.6.2.1 Service API update request 8.6.2.2 Service API update response 8.6.3 Procedure 8.7 Discover service APIs 8.7.1 General 8.7.2 Information flows 8.7.2.1 Service API discover request 8.7.2.2 Service API discover response 8.7.3 Procedure
...

8.5 Retrieve service APIs p. 49

8.5.1 General p. 49

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 flows p. 49

8.5.2.1 Service API get request p. 49

Table 8.5.2.1-1 describes the information flow service API get request from the API publishing function to the CAPIF core function.

Table 8.5.2.1-1: Service API get request

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 p. 49

Table 8.5.2.2-1 describes the information flow service API get response from the CAPIF core function to the API publishing function.

Table 8.5.2.2-1: Service API get response

Information element	Status	Description
Result	M	Indicates the success or failure of retrieving the service API information
Cause	O	The cause for the request failure.
Service API information	O (see NOTE)	The service API information as specified in Table 8.3.2.1-1.
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.

8.5.3 Procedure p. 49

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:

Authorization details of the APF are available with the CAPIF core function.

Reproduction of 3GPP TS 23.222, Fig. 8.5.3-1: Retrieve service APIs

Figure 8.5.3-1: Retrieve service APIs

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

Step 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).

Step 3.

The CAPIF core function provides a service API get response to the API publishing function which includes the service API information.

8.6 Update service APIs p. 50

8.6.1 General p. 50

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 p. 50

8.6.2.1 Service API update request p. 50

Table 8.6.2.1-1 describes the information flow service API update request from the API publishing function to the CAPIF core function.

Table 8.6.2.1-1: Service API update request

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 as specified in Table 8.3.2.1-1, as required to replace the existing service API information.
Reason	O	The reason of the update (e.g. change log).

8.6.2.2 Service API update response p. 51

Table 8.6.2.2-1 describes the information flow service API update response from the CAPIF core function to the API publishing function.

Table 8.6.2.2-1: Service API update response

Information element	Status	Description
Result	M	Indicates the success or failure of updating the service API information.
Cause	O	The cause for the request failure.
Service API information	O	The authorized service API information during update, applicable when the update result is success. This can be a subset or the full set, of the Service API information as specified in Table 8.3.2.1-1.

8.6.3 Procedure p. 51

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:

Authorization details of the APF are available with the CAPIF core function.
API invokers may have subscribed with the CAPIF core function to obtain notification regarding update to service API information.

Reproduction of 3GPP TS 23.222, Fig. 8.6.3-1: Update service APIs

Figure 8.6.3-1: Update service APIs

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

Step 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).

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

8.7 Discover service APIs p. 52

8.7.1 General p. 52

The following procedure in this subclause corresponds to the architectural requirements on discover service APIs. This procedure may be invoked by different types of API invokers (i.e., application management client, hosted application) at different phases (i.e., hosted application development, test phase and hosted application running phase). Different API invokers utlize this procedure for different purpose:

service API discovery for interested service APIs with service API informaiton including e.g., API name, API provider name, API category.
service API discovery for the interface information (e.g. IP address, port number, URI) of a particular service API in case of the interface information is not provided in the service API information during hosted application running phase.

8.7.2 Information flows p. 52

8.7.2.1 Service API discover request p. 52

Table 8.7.2.1-1 describes the information flow service API discover request from the API invoker to the CAPIF core function.

Table 8.7.2.1-1: Service API discover request

Information element	Status	Description
API invoker identity information	M	Identity information of the API invoker discovering service APIs
Query information	O (NOTE 2)	Criteria for discovering matching service APIs (e.g. service API category, Serving Area Information (optional), preferred AEF location (optional), required API provider name (optional), UE IP address (optional), interfaces, protocols, Service KPIs (optional), security methods, service API operation(s) and resource(s) (optional), and Network Slice Info (optional)). (see NOTE 1).
Service API identification	O (NOTE 2)	The identification information of the service API(s) for which the request is targeting.
NOTE 1: It should be possible to discover all the service APIs. NOTE 2: Either "Query information" IE or " Service API identification" IE shall be present.

8.7.2.2 Service API discover response p. 52

Table 8.7.2.2-1 describes the information flow service API discover response from the CAPIF core function to the API invoker.

Table 8.7.2.2-1: Service API discover response

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, NOTE 3)	The service API information as specified in Table 8.3.2.1-1, except for the service API status (e.g. active, inactive).
Interface information	O (NOTE 3)	The interface details (e.g. IP address, port number, URI) of the requested service API(s).
CAPIF core function identity information	O (see NOTE 1, NOTE 3)	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. NOTE 3: "Interface information" IE shall not be present when "Service API information" or "CAPIF core function identity information" is present.

8.7.3 Procedure p. 53

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:

The API invoker is onboarded and has received an API invoker identity.
The CAPIF core function is configured with a discovery policy information (e.g. to restrict discovery to category of APIs) for API invoker(s).

Reproduction of 3GPP TS 23.222, Fig. 8.7.3-1: Discover service APIs

Figure 8.7.3-1: Discover service APIs

Step 1.

The API invoker sends a service API discover request to the CAPIF core function. It includes the API invoker identity, either query information or the service API identification.

For service API discovery for interested service APIs, the query information is included.

For service API discovery for interface information, service API identification is included.

Step 2.

Upon receiving the service API discover request, the CAPIF core function verifies the identity of the API invoker (via authentication).

If the query information is included, 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.

If the service API identification is included, the CAPIF core function retrieves the interface information of the requested service API(s).

Step 3.

The CAPIF core function sends a service API discover response to the API invoker.

If the query information is included, the list of service API information is returned.

If the service API identification is included, the interface information is returned.