6 Functional model
23.2223GPPCommon API Framework for 3GPP Northbound APIsRelease 18TS
6.1 General
The Common API framework (CAPIF) functional architecture is described in this subclause. The CAPIF architecture is defined as service-based and interactions between the CAPIF functions are represented in two ways:
– A service-based representation, where CAPIF functions enable other authorized CAPIF functions to access their services;
– A reference point representation, where interactions between any two CAPIF functions (e.g. CCF, AEF) is shown by an appropriate point-to-point reference point (e.g. CAPIF-3).
The CAPIF functional architecture can be adopted by any 3GPP functionality providing 3GPP northbound service APIs.
NOTE: The terms “functional architecture” and “functional model” mean the same and have been used interchangeably in this specification.
6.2 Functional model description
6.2.0 Functional model description for the CAPIF
Figure 6.2.0-1 shows the reference point based functional model for the CAPIF.
Figure 6.2.0-1: Functional model for the CAPIF
The CAPIF is hosted within the PLMN operator network. The API invoker is typically provided by a 3rd party application provider who has service agreement with PLMN operator. The API invoker may reside within the same trust domain as the PLMN operator network.
In a reference point based model, the API invoker within the PLMN trust domain interacts with the CAPIF via CAPIF-1 and CAPIF-2. The API invoker from outside the PLMN trust domain interacts with the CAPIF via CAPIF-1e and CAPIF-2e. The API exposing function, the API publishing function and the API management function of the API provider domain (together known as API provider domain functions) within the PLMN trust domain interacts with the CAPIF core function via CAPIF-3, CAPIF-4 and CAPIF-5 respectively.
Figure 6.2.0-2: Functional model for interactions between API exposing functions
As illustrated in figure 6.2.0-2, the interactions between the API exposing functions within the PLMN trust domain is via CAPIF-7.
The CAPIF core function provides CAPIF APIs to the API invoker over CAPIF-1 and CAPIF-1e. The API exposing function provides the service APIs to the API invoker over CAPIF-2 and CAPIF-2e.
NOTE 1: The communication between the API exposing function and the CAPIF core function, between the API publishing function and the CAPIF core function and between the API management function and the CAPIF core function over CAPIF-3, CAPIF-4 and CAPIF-5 respectively can be API based.
The detailed information of the APIs provided by the CAPIF core function is specified in clause 10.
The security aspects of CAPIF reference points are specified in 3GPP TS 33.122 [12].
Figure 6.2.0-3 illustrates the CAPIF functional model using service-based interfaces.
Figure 6.2.0-3: CAPIF functional model representation using service-based interfaces
Table 6.2.0-1 specifies the service-based interfaces supported by CAPIF.
Table 6.2.0-1: Service-based interfaces supported by CAPIF
|
Service-based interface |
Entity |
APIs offered |
|
Cccf |
CAPIF core function |
Specified in subclause 10 |
|
Caef |
API exposing function |
Specified in subclause 11 |
6.2.1 Functional model description to support 3rd party API providers
Figure 6.2.1-1 shows the functional model for the CAPIF to support 3rd party API providers.
Figure 6.2.1-1: Functional model for the CAPIF to support 3rd party API providers
The CAPIF core function in the PLMN trust domain supports service APIs from both the PLMN trust domain and the 3rd party trust domain having business relationship with PLMN. The API invokers may exist within the PLMN trust domain, or within the 3rd party trust domain or outside of both the PLMN trust domain and the 3rd party trust domain. The API provider domain 1 offers the service APIs from the PLMN operator. The API provider domain 2 offers the service APIs from the 3rd party. When the 3rd party API provider is a trusted 3rd party of the PLMN, the API provider domain 1 also offers the service APIs from the 3rd party.
The API invoker 2 within the PLMN trust domain interacts with the CAPIF core function via CAPIF-1, and invokes the service APIs in the PLMN trust domain via CAPIF-2 and invokes the service APIs in the 3rd party trust domain via CAPIF-2e. The API invoker 3 within the 3rd party trust domain interacts with the CAPIF core function via CAPIF-1e, and invokes the service APIs in the PLMN trust domain via CAPIF-2e and invokes the service APIs in 3rd party trust domain via CAPIF-2. The API invoker 1 from outside the PLMN trust domain and 3rd party trust domain, interacts with the CAPIF core function via CAPIF-1e and invokes the service APIs in the PLMN trust domain and the service APIs in the 3rd party trust domain via CAPIF-2e.
The API exposing function, the API publishing function and the API management function of the API provider domain 1 within the PLMN trust domain interacts with the CAPIF core function via CAPIF-3, CAPIF-4 and CAPIF-5 respectively. The API exposing function, the API publishing function and the API management function of the API provider domain 2 within the 3rd party trust domain interacts with the CAPIF core function in the PLMN trust domain via CAPIF-3e, CAPIF-4e and CAPIF-5e respectively. The API exposing function within the PLMN trust domain and the 3rd party trust domain provides the service APIs to the API invoker, offered by the respective trust domains.
The interactions between the API exposing functions within the PLMN trust domain is via CAPIF-7 (not shown in the figure 6.2.1-1 for simplicity). The API exposing function within the PLMN trust domain interacts with the API exposing function in the 3rd party trust domain via CAPIF-7e.
NOTE 1: The communication between the API exposing function and the CAPIF core function, between the API publishing function and the CAPIF core function and between the API management function and the CAPIF core function over CAPIF-3/3e, CAPIF-4/4e and CAPIF-5/5e respectively can be API based.
The detailed information of the APIs provided by the CAPIF core function is specified in clause 10.
NOTE 2: The security aspects of CAPIF reference points are under SA3 responsibility and out of scope of the present document.
6.2.2 Functional model description to support CAPIF interconnection
Figure 6.2.2-1 shows the architectural model for the CAPIF interconnection which allows API invokers of a CAPIF provider to utilize the service APIs from the 3rd party CAPIF provider.
Figure 6.2.2-1: High level functional architecture for CAPIF interconnection with multiple CAPIF provider domains
Figure 6.2.2-2 shows the architectural model for the CAPIF interconnection within the same CAPIF provider domain, which allows API invokers of CAPIF core function 1 to utilize the service APIs from CAPIF core function 2, where both CAPIF core function 1 and CAPIF core function 2 are hosted within the trust domain of the CAPIF provider A.
Figure 6.2.2-2: High level functional architecture for CAPIF interconnection within a CAPIF provider domain
The CAPIF provider A and CAPIF provider B host the CAPIF in their trust domains. A business relationship exists between the CAPIF providers.
The CAPIF providers in their respective trust domain hosts multiple CAPIF instances where each CAPIF instance consists of the CAPIF core function (local), the API provider domain and the API invokers. All interactions within the CAPIF instance is according to the functional model specified in subclause 6.2.0.
When multiple CAPIF instances are deployed by a CAPIF provider there may be a hierarchy associated with the multiple CAPIF core function deployed which allows:
– the designated CAPIF core function of the CAPIF provider A to interconnect with the designated CAPIF core function of the CAPIF provider B; and
– within CAPIF provider A, one or more CAPIF core function interacts with the designated CAPIF core function 1.
The designated CAPIF core function of the CAPIF provider A provides the information about the CAPIF instances and service APIs deployed by the CAPIF provider A to the designated CAPIF core function of the CAPIF provider B and vice versa over CAPIF-6e reference point.
The CAPIF core function 2 of CAPIF provider A provides the information about the service APIs to the CAPIF core function 1 over CAPIF-6 reference point.
NOTE 1: Void
The API invokers may exist within the trust domain of CAPIF provider A, or within the trust domain of CAPIF provider B or outside of the trust domains of both CAPIF provider A and CAPIF provider B. The API invoker of a CAPIF provider is onboarded with the CAPIF core function in the corresponding trust domain of the CAPIF provider.
NOTE 2: For sake of simplicity, the service API interactions of API invokers of the CAPIF provider B are not shown. From each CAPIF provider’s perspective the other CAPIF provider is a 3rd party.
One or more CAPIF core function can publish service APIs to the designated CAPIF core function over CAPIF-6 reference point and, also discover the service APIs from the designated CAPIF core function and vice versa over CAPIF-6 reference point.
The API invoker within the trust domain of CAPIF provider A interacts with the CAPIF core function of the CAPIF provider A via CAPIF-1 and discovers the service APIs of both CAPIF providers, and invokes the service APIs in the trust domain of CAPIF provider A via CAPIF-2 and invokes the service APIs in the trust domain of CAPIF provider B via CAPIF-2e. The API invoker from outside the trust domain of CAPIF providers, interacts with the CAPIF core function of th CAPIF provider A via CAPIF-1e and invokes the service APIs in the trust domain of the CAPIF providers via CAPIF-2e.
NOTE 3: The communication between the CAPIF core function of the CAPIF providers over CAPIF-6 or CAPIF-6e can be API based.
The detailed information of the APIs provided by the CAPIF core function is specified in clause 10.
NOTE 4: The security aspects of CAPIF reference points are under SA3 responsibility and out of scope of the present document.
6.2.3 Functional model description to support SNA
Figure 6.2.3-1 shows the architectural model for the SNA which allows the resource owner to provide authorization to the API invocation.
Figure 6.2.3-1: High level functional architecture for CAPIF supporting SNA
The resource owner client(s) are application clients used by resource owners of the API provider domain’s service provider.
The resource owner client(s) interacts with the authorization function via CAPIF-8. The resource owner communicates with the authorization function to provide and revoke resource owner consent. The resource owner interactions are supported via a resource owner client, which is a client-side entity.
The API exposing function (e.g NEF) acts as a resource owner consent enforcement point as specified in 3GPP TS 33.501 [8] and interacts with the authorization function via CAPIF-9. The API exposing function can retrieve the resource owner consent parameters from.the authorization function.
The API invoker interacts with authorization function via CAPIF-10/CAPIF-10e.
NOTE: In the current release, 3rd party API providers (i.e., API providers outside the PLMN trust domain) are not supported for SNA.
Editor’s Note: Security aspects including specification of the authentication and authorisation procedures for UE-originated API invocation within CAPIF are FFS in SA3.
6.3 Functional entities description
6.3.1 General
Each subclause is a description of a functional entity and does not imply a physical entity.
6.3.2 API invoker
The API invoker is typically provided by a 3rd party application provider who has service agreement with PLMN operator. The API invoker may reside within the same trust domain as the PLMN operator network.
The API invoker supports the following capabilities:
– Triggering API invoker onboarding/offboarding;
– Supporting the authentication by providing the API invoker identity and other information required for authentication of the API invoker;
– Supporting mutual authentication with CAPIF;
– Obtaining the authorization prior to accessing the service API;
– Discovering service APIs information; and
– Invoking the service APIs.
NOTE: The details of the specific service APIs are out of scope of the present document.
6.3.3 CAPIF core function
The CAPIF core function consists of the following capabilities:
– Authenticating the API invoker based on the identity and other information required for authentication of the API invoker;
– Supporting mutual authentication with the API invoker;
– Providing authorization for the API invoker prior to accessing the service API;
– Publishing, storing and supporting the discovery of service APIs information;
– Controlling the service API access based on PLMN operator configured policies;
– Storing the logs for the service API invocations and providing the service API invocation logs to authorized entities;
– Charging based on the logs of the service API invocations;
– Monitoring the service API invocations;
– Onboarding a new API invoker and offboarding an API invoker;
– Storing policy configurations related to CAPIF and service APIs;
– Support accessing the logs for auditing (e.g. detecting abuse); and
– Supports publishing, discovery of service APIs information with another CAPIF core function in CAPIF interconnection.
6.3.4 API exposing function
The API exposing function is the provider of the service APIs and is also the service communication entry point of the service API to the API invokers. The API exposing function consists of the following capabilities:
– Authenticating the API invoker based on the identity and other information required for authentication of the API invoker provided by the CAPIF core function;
– Validating the authorization provided by the CAPIF core function; and
– Logging the service API invocations at the CAPIF core function.
6.3.5 API publishing function
The API publishing function enables the API provider to publish the service APIs information in order to enable the discovery of service APIs by the API invoker. The API publishing function consists of the following capability:
– Publishing the service API information of the API provider to the CAPIF core function.
6.3.6 API management function
The API management function enables the API provider to perform administration of the service APIs. The API management function consists of the following capabilities:
– Auditing the service API invocation logs received from the CAPIF core function;
– Monitoring the events reported by the CAPIF core function;
– Configuring the API provider policies to the CAPIF core function;
– Monitoring the status of the service APIs;
– Onboarding the new API invokers and offboarding API invokers; and
– Registering and maintaining registration information of the API provider domain functions on the CAPIF core function.
NOTE: The API invoker onboarding/offboarding in the API management function is out of the scope of the current release.
6.4 Reference points
6.4.1 General
The reference points for CAPIF are described in the following subclauses.
6.4.2 Reference point CAPIF-1 (between the API invoker and the CAPIF core function)
The CAPIF-1 reference point, which exists between the API invoker and the CAPIF core function, is used for the API invoker within the PLMN trust domain to discover service APIs, to authenticate and to get authorization.
The CAPIF-1 reference point supports:
– Onboarding the new API invokers and offboarding API invokers;
– Authenticating the API invoker based on the identity and credentials of the API invoker;
– Mutual authentication between the API invoker and the CAPIF core function;
– Providing authorization for the API invoker prior to accessing the service API; and
– Discovering the service APIs information.
NOTE: The security aspects of CAPIF-1 are specified in subclause 6.2 of 3GPP TS 33.122 [12].
6.4.3 Reference point CAPIF-1e (between the API invoker and the CAPIF core function)
The CAPIF-1e reference point, which exists between the API invoker and the CAPIF core function, is used for the API invoker outside the PLMN trust domain to discover service APIs, to authenticate and to get authorization.
The CAPIF-1e reference point supports all the functions of CAPIF-1.
NOTE: The security aspects of CAPIF-1e are specified in subclause 6.3 of 3GPP TS 33.122 [12].
6.4.4 Reference point CAPIF-2 (between the API invoker and the API exposing function)
The CAPIF-2 reference point, which exists between the API invoker and the API exposing function belonging to the same trust domain, is used for the API invoker to communicate with the service APIs.
The CAPIF-2 reference point supports:
– Authenticating the API invoker based on the identity and credentials of the API invoker;
– Authorization verification for the API invoker upon accessing the service API; and
– Invocation of service APIs.
NOTE 1: The aspects related to the specific service API invocation in reference point CAPIF-2 are out of scope of the present document.
NOTE 2: The security aspects of CAPIF-2 are specified in subclause 6.4 of 3GPP TS 33.122 [12].
6.4.5 Reference point CAPIF-2e (between the API invoker and the API exposing function)
The CAPIF-2e reference point, which exists between the API invoker and the API exposing function belonging to a different trust domain, is used for the API invoker to communicate with the service APIs.
The CAPIF-2e reference point supports all the functions of CAPIF-2.
NOTE: The security aspects of CAPIF-2e are specified in subclause 6.5 of 3GPP TS 33.122 [12].
6.4.6 Reference point CAPIF-3 (between the API exposing function and the CAPIF core function)
The CAPIF-3 reference point, which exists between the API exposing function and the CAPIF core function, is used for exercising access and policy related control for service API communications initiated by the API invoker.
The CAPIF-3 reference point supports:
– Authenticating the API invoker based on the identity and credentials of the API invoker;
– Providing authorization for the API invoker prior to accessing the service API;
– Authorization verification for the API invoker upon accessing the service API;
– Controlling the service API access based on PLMN operator configured policies;
– Logging the service API invocations; and
– Charging the service API invocations.
NOTE: The security aspects of CAPIF-3 are specified in subclause 6.6 of 3GPP TS 33.122 [12].
6.4.7 Reference point CAPIF-4 (between the API publishing function and the CAPIF core function)
The CAPIF-4 reference point, which exists between the API publishing function and the CAPIF core function, is used for publishing the service API information.
The CAPIF-4 reference point supports:
– Publishing the service APIs information by the API publishing function.
NOTE: The security aspects of CAPIF-4 are specified in subclause 6.6 of 3GPP TS 33.122 [12].
6.4.8 Reference point CAPIF-5 (between the API management function and the CAPIF core function)
The CAPIF-5 reference point, which exists between the API management function and the CAPIF core function, is used for management of service API, API invoker and API provider domain function information.
The CAPIF-5 reference point supports:
– Accessing the service API invocation logs by the API management function;
– Enabling the API management function to monitor the events reported due to the service APIs invocations;
– Onboarding new API invokers by provisioning the API invoker information at the CAPIF core function, requesting explicit grant of new API invokers onboarding and confirming onboarding success;
– Offboarding API invokers;
– Enabling the API management function to configure policies at the CAPIF core function e.g. service API invocation throttling, blocking API invocation for certain duration;
– Enabling the API provider to monitor the status of service APIs (e.g. pilot or live status, start or stop status of service API);
– Registering API provider domain functions on the CAPIF core function; and
– Update of the registration information of API provider domain functions on the CAPIF core function.
NOTE 1: The security aspects of CAPIF-5 are specified in subclause 6.6 of 3GPP TS 33.122 [12].
NOTE 2: The API invoker onboarding/offboarding over CAPIF-5 is out of the scope of the current release.
6.4.9 Reference point CAPIF-3e (between the API exposing function and the CAPIF core function)
The CAPIF-3e reference point, which exists between the API exposing function within the 3rd party trust domain and the CAPIF core function within the PLMN trust domain, is used for exercising access and policy related control for service API communications initiated by the API invoker.
The CAPIF-3e supports all the functions of CAPIF-3.
NOTE: The security aspects of CAPIF-3e will be specified by SA3.
Editor’s note: Reference to the appropriate SA3 specification is needed.
6.4.10 Reference point CAPIF-4e (between the API publishing function and the CAPIF core function)
The CAPIF-4e reference point, which exists between the API publishing function within the 3rd party trust domain and the CAPIF core function within the PLMN trust domain, is used for publishing the service API information.
The CAPIF-4e reference point supports all the functions of CAPIF-4.
NOTE: The security aspects of CAPIF-4e will be specified by SA3.
Editor’s note: Reference to the appropriate SA3 specification is needed.
6.4.11 Reference point CAPIF-5e (between the API management function and the CAPIF core function)
The CAPIF-5e reference point, which exists between the API management function within the 3rd party trust domain and the CAPIF core function within the PLMN trust domain, is used for management of service API, API invoker and API provider domain function information.
The CAPIF-5e reference point supports all the functions of CAPIF-5.
NOTE: The security aspects of CAPIF-5e will be specified by SA3.
Editor’s note: Reference to the appropriate SA3 specification is needed.
6.4.12 Reference point CAPIF-7 (between the API exposing functions)
The CAPIF-7 reference point, which exists between the API exposing functions belonging to the same trust domain, is used for the forwarding or routing of the API invoker’s service API invocation from one API exposing function to the other API exposing function deployed in the PLMN trust domain.
The CAPIF-7 reference point supports all the functions of CAPIF-2.
The CAPIF-7 reference point supports invocation of service APIs originated by the API invoker using CAPIF-2.
NOTE 1: The aspects related to the specific service API invocation in reference point CAPIF-7 are out of scope of the present document.
NOTE 2: The security aspects of CAPIF-7 are the responsibility of SA3.
6.4.13 Reference point CAPIF-7e (between the API exposing functions)
The CAPIF-7e reference point, which exists between the API exposing functions belonging to different trust domains, is used for the forwarding or routing of the API invoker’s service API invocation from one API exposing function to the other API exposing function between different trust domains.
The CAPIF-7e reference point supports all the functions of CAPIF-2e.
NOTE: The security aspects of CAPIF-7e are the responsibility of SA3.
6.4.14 Reference point CAPIF-6 (between the CAPIF core functions of the same CAPIF provider)
The CAPIF-6 reference point exists between the CAPIF core functions within the same trust domain of CAPIF provider.
The CAPIF-6 reference point supports:
– Publishing the service APIs information; and
– Discovering the service APIs information.
6.4.15 Reference point CAPIF-6e (between the CAPIF core functions of different CAPIF providers)
The CAPIF-6e reference point exists between the CAPIF core function within the 3rd party trust domain and the CAPIF core function within the PLMN trust domain.
The CAPIF-6e reference point supports all the functions of CAPIF-6.
NOTE: The security aspects of CAPIF-6e will be specified by SA3.
Editor’s note: Reference to the appropriate SA3 specification is needed.
6.5 Service-based interfaces
The CAPIF architecture contains the following service-based interfaces:
– Cccf: Service-based interface exhibited by CAPIF core function.
– Caef: Service-based interface exhibited by API exposing function.