8.7 CAPIF_Logging_API_Invocation_API

29.2223GPPCommon API Framework for 3GPP Northbound APIsRelease 18TS

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

8.7.1 API URI

The CAPIF_Logging_API_Invocation_API service shall use the CAPIF_Logging_API_Invocation_API.

The request URIs used in HTTP requests from the API exposing function towards the CAPIF core function shall have the Resource URI structure as defined in clause 7.5 with the following clarifications:

– The <apiName> shall be "api-invocation-logs".

– The <apiVersion> shall be "v1".

– The <apiSpecificSuffixes> shall be set as described in clause 8.7.2

8.7.2 Resources

8.7.2.1 Overview

This clause describes the structure for the Resource URIs and the resources and methods used for the service.

Figure 8.7.2.1-1 depicts the resource URIs structure for the CAPIF_Logging_API_Invocation_API.

Figure 8.7.2.1-1: Resource URI structure of the CAPIF_Logging_API_Invocation_API

Table 8.7.2.1-1 provides an overview of the resources and applicable HTTP methods.

Table 8.7.2.1-1: Resources and methods overview

Resource name	Resource URI	HTTP method or custom operation	Description
Logs	/{aefId}/logs	POST	Creates a new log entry for service API invocations
Individual log	/{aefId}/logs/{logId}	n/a	Individual log entry

8.7.2.2 Resource: Logs

8.7.2.2.1 Description

The Logs resource represents all the log entries created by a API exposing function at CAPIF core function.

8.7.2.2.2 Resource Definition

Resource URI: {apiRoot}/api-invocation-logs/<apiVersion>/{aefId}/logs

This resource shall support the resource URI variables defined in table 8.7.2.2.2-1.

Table 8.7.2.2.2-1: Resource URI variables for this resource

Name	Data Type	Definition
apiRoot	string	See clause 7.5
aefId	string	Identifies of the API exposing function

8.7.2.2.3 Resource Standard Methods

8.7.2.2.3.1 POST

This method shall support the URI query parameters specified in table 8.7.2.2.3.1-1.

Table 8.7.2.2.3.1-1: URI query parameters supported by the POST method on this resource

Name	Data type	P	Cardinality	Description
n/a

This method shall support the request data structures specified in table 8.7.2.2.3.1-2 and the response data structures and response codes specified in table 8.7.2.2.3.1-3.

Table 8.7.2.2.3.1-2: Data structures supported by the POST Request Body on this resource

Data type	P	Cardinality	Description
InvocationLog	M	1	Log of service API invocations provided by API exposing function to store on the CAPIF core function.

Table 8.7.2.2.3.1-3: Data structures supported by the POST Response Body on this resource

Data type

Cardinality

Response

codes

Description

InvocationLog

201 Created

Log of service API invocations provided by API exposing function successfully stored on the CAPIF core function.

The URI of the created resource shall be returned in the "Location" HTTP header.

NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [14] also apply.

Table 8.7.2.2.3.1-4: Headers supported by the 201 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	Contains the URI of the newly created resource, according to the structure: {apiRoot}/api-invocation-logs/<apiVersion>/{aefId}/logs/{logId}

8.7.2.2.4 Resource Custom Operations

None.

8.7.3 Notifications

None.

8.7.4 Data Model

8.7.4.1 General

This clause specifies the application data model supported by the API. Data types listed in clause 7.2 also apply to this API.

Table 8.7.4.1-1 specifies the data types defined specifically for the CAPIF_Logging_API_Invocation_API service.

Table 8.7.4.1-1: CAPIF_Logging_API_Invocation_API specific Data Types

Data type	Section defined	Description	Applicability
DurationMs	Clause 8.7.4.3.2	Represents the period of time in units of milliseconds.
InvocationLog	Clause 8.7.4.2.2	Represents the set of Service API invocation logs to be stored on CAPIF core function.
Log	Clause 8.7.4.2.3	Represents the individual service API invocation log entry.

Table 8.7.4.1-2 specifies data types re-used by the CAPIF_Logging_API_Invocation_API service.

Table 8.7.4.1-2: Re-used Data Types

Data type	Reference	Comments	Applicability
DateTime	3GPP TS 29.122 [14]	Used to indicate the invocation time.
Operation	Clause 8.2.4.3.7	Used to indicate the HTTP operation
SupportedFeatures	3GPP TS 29.571 [19]	Used to negotiate the applicability of optional features defined in table 8.7.6-1.

8.7.4.2 Structured data types

8.7.4.2.1 Introduction

This clause defines the structured data types to be used in resource representations of the CAPIF_Logging_API_Invocation_API.

8.7.4.2.2 Type: InvocationLog

Table 8.7.4.2.2-1: Definition of type InvocationLog

Attribute name	Data type	P	Cardinality	Description	Applicability
aefId	string	M	1	Identity information of the API exposing function requesting logging of service API invocations
apiInvokerId	string	M	1	Identity of the API invoker which invoked the service API
logs	array(Log)	M	1..N	Service API invocation log
supportedFeatures	SupportedFeatures	O	0..1	Used to negotiate the supported optional features of the API as described in clause 7.8. This attribute shall be provided in the HTTP POST request and in the response of successful resource creation.

8.7.4.2.3 Type: Log

Table 8.7.4.2.3-1: Definition of type Log

Attribute name	Data type	P	Cardinality	Description	Applicability
apiId	string	M	1	String identifying the API invoked.
apiName	string	M	1	Name of the API which was invoked, it is set as {apiName} part of the URI structure as defined in clause 5.2.4 of 3GPP TS 29.122 [14].
apiVersion	string	M	1	Version of the API which was invoked
resourceName	String	M	1	Name of the specific resource invoked
uri	Uri	0	0..1	Full URI of the API resource as defined in clause 5.2.4 of 3GPP TS 29.122 [14].
protocol	Protocol	M	1	Protocol invoked.
operation	Operation	C	0..1	Operation that was invoked on the API, only applicable for HTTP protocol.
result	string	M	1	For HTTP protocol, it contains HTTP status code of the invocation
invocationTime	DateTime	O	0..1	Date on which it was invoked
invocationLatency	DurationMs	O	0..1	Latency for the API invocation.
inputParameters	ANY TYPE (NOTE)	O	0..1	List of input parameters
OutputParameters	ANY TYPE (NOTE)	O	0..1	List of output parameters
srcInterface	InterfaceDescription	O	0..1	Interface description of the API invoker.
destInterface	InterfaceDescription	O	0..1	Interface description of the API invoked.
fwdInterface	string	O	0..1	It includes the node identifier (as defined in IETF RFC 7239 [20] of all forwarding entities between the API invoker and the AEF, concatenated with comma and space, e.g. 192.0.2.43:80, unknown:_OBFport, 203.0.113.60
NOTE: Any basic data type defined in OpenAPI Specification [3] may be used.

8.7.4.3 Simple data types and enumerations

8.7.4.3.1 Introduction

This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses.

8.7.4.3.2 Simple data types

The simple data types defined in table 8.7.4.3.2-1 shall be supported.

Table 8.7.4.3.2-1: Simple data types

Type Name	Type Definition	Description	Applicability
DurationMs	integer	Unsigned integer identifying a period of time in units of milliseconds.

8.7.5 Error Handling

8.7.5.1 General

HTTP error handling shall be supported as specified in clause 7.7.

In addition, the requirements in the following clauses shall apply.

8.7.5.2 Protocol Errors

In this Release of the specification, there are no additional protocol errors applicable for the CAPIF_Logging_API_Invocation_API.

8.7.5.3 Application Errors

The application errors defined for the CAPIF_Logging_API_Invocation_API are listed in table 8.7.5.3-1.

Table 8.7.5.3-1: Application errors

Application Error	HTTP status code	Description	Applicability

8.7.6 Feature negotiation

Table 8.7.8-1: Supported Features

Feature number	Feature Name	Description
n/a