7 CAPIF Design Aspects Common for All APIs

29.2223GPPCommon API Framework for 3GPP Northbound APIsRelease 18TS

Tools: ARFCN - Frequency Conversion for 5G NR/LTE/UMTS/GSM

7.1 General

CAPIF APIs are RESTful APIs that allow secure access to the capabilities provided by CAPIF.

This document specifies the procedures triggered at different functional entities as a result of API invocation requests and event notifications. The stage-2 level requirements and signalling flows are defined in 3GPP TS 23.222 [2].

Several design aspects, as mentioned in the following clauses, are specified in 3GPP TS 29.122 [14] and referenced by this specification.

7.2 Data Types

7.2.1 General

This clause defines structured data types, simple data types and enumerations that are applicable to several APIs defined in the present specification and can be referenced from data structures defined in the subsequent clauses.

In addition, data types that are defined in OpenAPI Specification [3] can also be referenced from data structures defined in the subsequent clauses.

NOTE: As a convention, data types in the present specification are written with an upper-case letter in the beginning. Parameters are written with a lower-case letter in the beginning. Enumerations are written using UPPER_WITH_UNDERSCORE case convention. As an exception, data types that are also defined in OpenAPI Specification [3] can use a lower-case case letter in the beginning for consistency.

Table 7.2.1-1 specifies data types re-used by the CAPIF from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the CAPIF.

Table 7.2.1-1: Re-used Data Types

Data type	Reference	Comments
Uri	3GPP TS 29.122 [14]
TestNotification	3GPP TS 29.122 [14]	Following clarifications apply: – The SCEF is the CAPIF core function; and – The SCS/AS is the Subscriber.
WebsockNotifConfig	3GPP TS 29.122 [14]	Following clarifications apply: – The SCEF is the CAPIF core function; and – The SCS/AS is the Subscriber.

7.2.2 Referenced structured data types

Table 7.2.2-1 lists structured data types defined in this specification referenced by multiple services:

Table 7.2.2-1: Referenced Structured Data Types

Data type	Reference	Description
Log	Clause 8.7.4.2.3	Individual log entries
InterfaceDescription	Clause 8.2.4.2.3	Description of the API interface
ServiceAPIDescription	Clause 8.2.4.2.2	Description of the service API

7.2.3 Referenced Simple data types and enumerations

Following simple data types defined in Table 7.2.3.1-1 are applicable to several APIs in this document:

Table 7.2.3.1-1: Simple data types applicable to several APIs

Type name	Reference	Description
CAPIFResourceId	n/a	string chosen by the CAPIF core function to serve as identifier in a resource URI.
DataFormat	Clause 8.2.4.3.4	Data format used by the API
Protocol	Clause 8.2.4.3.3	Protocol used by the API

7.3 Usage of HTTP

For CAPIF APIs, support of HTTP/1.1 (IETF RFC 7230 [4], IETF RFC 7231 [5], IETF RFC 7232 [6], IETF RFC 7233 [7], IETF RFC 7234 [8] and IETF RFC 7235 [9]) over TLS is mandatory and support of HTTP/2 (IETF RFC 7540 [10]) over TLS is recommended. TLS shall be used as specified in 3GPP TS 33.122 [16].

A functional entity desiring to use HTTP/2 shall use the HTTP upgrade mechanism to negotiate applicable HTTP version as described in IETF RFC 7540 [10].

7.4 Content type

The bodies of HTTP request and successful HTTP responses shall be encoded in JSON format (see IETF RFC 8259 [12]).

The MIME media type that shall be used within the related Content-Type header field is "application/json", as defined in IETF RFC 8259 [12] , unless specified otherwise in the API definition.

The JSON objects defined in clause 5.2.3 of 3GPP TS 29.122 [14] for the HTTP PATCH request shall be supported.

7.5 URI structure

7.5.1 Resource URI structure

All API URIs of CAPIF APIs shall be:

{apiRoot}/<apiName>/<apiVersion>

"apiRoot" is configured by means outside the scope of the present document. It includes the scheme ("https"), host and optional port, and an optional prefix string. "apiName" and "apiVersion" shall be set dependent on the API, as defined in the corresponding clauses below.

All resource URIs in the clauses below are defined relative to the above root API URI.

NOTE 1: The "apiVersion" will only be increased if the new API version contains backward incompatible changes. Otherwise, the supported feature mechanism defined in clause 7.8 can be used to negotiate extensions.

NOTE 2: A different root structure can be used when the resource URI is preconfigured in the API invoking entity.

The root structure may be followed by "apiSpecificSuffixes" that are dependent on the API and are defined separately for each API as resource URI where they apply:

{apiRoot}/<apiName>/<apiVersion>/<apiSpecificSuffixes>

The naming conventions defined in subclause 5.2.4 of 3GPP TS 29.122 [14] shall apply.

7.5.2 Custom operations URI structure

The custom operation definition is in Annex C of 3GPP TS 29.501 [18].

The URI of a custom operation which is associated with a resource shall have the following structure:

{apiRoot}/<apiName>/<apiVersion>/<apiSpecificResourceUriPart>/<custOpName>

Custom operations can also be associated with the service instead of a resource. The URI of a custom operation which is not associated with a resource shall have the following structure:

{apiRoot}/<apiName>/<apiVersion>/<custOpName>

In the above URI structures, "apiRoot", "apiName", "apiVersion" and "apiSpecificResourceUriPart" are as defined in clause 7.5.1 and "custOpName" represents the name of the custom operation as defined in clause 5.1.3.2 of 3GPP TS 29.501 [18].

7.6 Notifications

The functional entities

– shall support the delivery of notifications using a separate HTTP connection towards an address;

– may support testing delivery of notifications; and

– may support the delivery of notification using WebSocket protocol (see IETF RFC 6455 [13]),

as described in 3GPP TS 29.122 [14], with the following clarifications:

– the SCEF is the CAPIF core function; and

– the SCS/AS is the Subscriber.

7.7 Error handling

HTTP error handling described in clause 5.2.6 of 3GPP TS 29.122 [14] is applicable to all APIs in the present specification unless specified otherwise, with the following clarifications:

– the SCEF is the CAPIF core function; and

– the SCS/AS is the functional entity invoking an API.

7.8 Feature negotiation

The functional entity invoking an API (i.e. the API invoker, the API exposing function, the API publishing function or the API management function) and the CAPIF core function use feature negotiation procedures defined in 3GPP TS 29.122 [14] to negotiate the supported features, with the following clarifications:

– description of the SCEF applies to the CAPIF core function;

– description of the SCS/AS applies to the functional entity invoking an API;

– the CAPIF Core Function should not register any feature in the NRF; and

– the AEF should not register any feature for AEF_Security_API in the NRF.

7.9 HTTP headers

The HTTP headers and the HTTP custom headers described in 3GPP TS 29.122 [14] are applicable to all APIs in this document.

7.10 Conventions for Open API specification files

The conventions for Open API specification files as specified in clause 5.2.9 of 3GPP TS 29.122 [14] shall be applicable for all APIs in this document.