6 API Definitions

29.5643GPP5G SystemRelease 17Stage 3TSUser Plane Function Services

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

6.1 Nupf_EventExposure Service API

6.1.1 API URI

The Nupf_EventExposure shall use the Nupf_EventExposure API.

The API URI of the Nupf_EventExposure API shall be:

{apiRoot}/<apiName>/<apiVersion>

The request URIs used in HTTP requests from the NF service consumer towards the NF service producer shall have the Resource URI structure defined in clause 4.4.1 of 3GPP TS 29.501 [5], i.e.:

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

with the following components:

– The {apiRoot} shall be set as described in 3GPP TS 29.501 [5].

– The <apiName> shall be "nupf-ee".

– The <apiVersion> shall be "v1".

– The <apiSpecificResourceUriPart> shall be set as described in clause 6.1.3.

6.1.2 Usage of HTTP

6.1.2.1 General

HTTP/2, IETF RFC 7540 [11], shall be used as specified in clause 5 of 3GPP TS 29.500 [4].

HTTP/2 shall be transported as specified in clause 5.3 of 3GPP TS 29.500 [4].

The OpenAPI [6] specification of HTTP messages and content bodies for the Nupf_EventExposure API is contained in Annex A.

6.1.2.2 HTTP standard headers

6.1.2.2.1 General

See clause 5.2.2 of 3GPP TS 29.500 [4] for the usage of HTTP standard headers.

6.1.2.2.2 Content type

JSON, IETF RFC 8259 [12], shall be used as content type of the HTTP bodies specified in the present specification as specified in clause 5.4 of 3GPP TS 29.500 [4]. The use of the JSON format shall be signalled by the content type "application/json".

"Problem Details" JSON object shall be used to indicate additional details of the error in a HTTP response body and shall be signalled by the content type "application/problem+json", as defined in IETF RFC 7807 [13].

6.1.2.3 HTTP custom headers

The mandatory HTTP custom header fields specified in clause 5.2.3.2 of 3GPP TS 29.500 [4] shall be supported, and the optional HTTP custom header fields specified in clause 5.2.3.3 of 3GPP TS 29.500 [4] may be supported.

In this release of this specification, no custom headers specific to the Nupf_EventExposure service are defined.

6.1.3 Resources

6.1.3.1 Overview

Figure 6.1.3.1-1: Resource URI structure of the nupf-ee API

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

Table 6.1.3.1-1: Resources and methods overview

Resource name

Resource URI

HTTP method or custom operation

Description

EventExposureSubscriptions

(Collection)

/ee-subscriptions

POST

This is a pseudo operation.

6.1.3.2 Resource: EventExposureSubscriptions

6.1.3.2.1 Description

6.1.3.2.2 Resource Definition

Resource URI: {apiRoot}/nupf-ee/<apiVersion>/ee-subscriptions

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

Table 6.1.3.2.2-1: Resource URI variables for this resource

Name	Data type	Definition
apiRoot	string	See clause 6.1.1
apiVersion	string	See clause 6.1.1

6.1.3.2.3 Resource Standard Methods

6.1.3.2.3.1 POST

This method will not be actually invoked.

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

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

Name	Data type	P	Cardinality	Description	Applicability
n/a

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

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

Data type	P	Cardinality	Description
Any

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

Data type

Cardinality

Response

codes

Description

n/a

NOTE: The mandatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply.

6.1.4 void

6.1.5 Notifications

6.1.5.1 General

Notifications shall comply to clause 6.2 of 3GPP TS 29.500 [4] and clause 4.6.2.3 of 3GPP TS 29.501 [5].

Table 6.1.5.1-1: Notifications overview

Notification

Callback URI

HTTP method or custom operation

Description

(service operation)

Event Notification

{eventNotificationUri} (This URI is not provided by NF service consumer via Nupf interface, it is provided via N4 interface during the provisioning of Session Reporting Rule)

POST

Notify about the events that UPF exposes and to which the NF service consumer may subscribe to.

6.1.5.2 Event Notification

6.1.5.2.1 Description

The Event Notification is used by the UPF to report one or several observed Events to a NF service consumer that has subscribed to such Notifications.

6.1.5.2.2 Target URI

The POST method shall be used for Event Notification and the URI shall be the Event Notification URI provided by the SMF during the provisioning of Session Reporting Rule, see clause 5.33.5 of 3GPP TS 29.244 [15].

Resource URI: {eventNotificationUri}

Support of URI query parameters is specified in table 6.1.5.2.2-1.

Table 6.1.5.2.2-1: Callback URI variables

Name	Data type	P	Cardinality	Description
n/a

Support of request data structures is specified in table 6.1.5.2.2-2, and support of response data structures and response codes is specified in table 6.1.5.2.2-3.

Table 6.1.5.2.2-2: Data structures supported by the POST Request Body

Data type	P	Cardinality	Description
NotificationData	M	1	Representation of the event notification.

Table 6.1.5.2.2-3: Data structures supported by the POST Response Body

Data type	P	Cardinality	Response codes	Description
n/a			204 No Content	This case represents a successful notification of the event.
ProblemDetails	O	0..1	404 Not Found	If the NF Service Consumer considers the "eventNotificationUri" and/or "Notification Correlation ID" is not recognized, the NF Service Consumer shall return "404 Not Found" status code
RedirectResponse	O	0..1	307 Temporary Redirect	The NF service consumer shall generate a Location header field containing a URI pointing to the endpoint of another NF Service Consumer instance to which the notification should be sent. If an SCP redirects the message to another SCP then the location header field shall contain the same URI or a different URI pointing to the endpoint of the NF service consumer to which the notification should be sent.
RedirectResponse	O	0..1	308 Permanent Redirect	The NF service consumer shall generate a Location header field containing a URI pointing to the endpoint of another NF Service Consumer instance to which the notification should be sent. If an SCP redirects the message to another SCP then the location header field shall contain the same URI or a different URI pointing to the endpoint of the NF service consumer to which the notification should be sent.
NOTE: The mandatory HTTP error status codes for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] other than those specified in the table above also apply, with a ProblemDetails data type (see clause 5.2.7 of 3GPP TS 29.500 [4]).

Table 6.1.5.2.2-4: Headers supported by the 307 Response Code on this endpoint

Name	Data type	P	Cardinality	Description
Location	string	M	1	A URI pointing to the endpoint of the NF service consumer instance to which the request should be sent
3gpp-Sbi-Target-Nf-Id	string	O	0..1	Identifier of the target NF instance ID towards which the notification is redirected

Table 6.1.5.2.2-5: Headers supported by the 308 Response Code on this endpoint

Name	Data type	P	Cardinality	Description
Location	string	M	1	A URI pointing to the endpoint of the NF service consumer instance to which the request should be sent
3gpp-Sbi-Target-Nf-Id	string	O	0..1	Identifier of the target NF instance ID towards which the notification is redirected

6.1.6 Data Model

6.1.6.1 General

This clause specifies the application data model supported by the API.

Table 6.1.6.1-1 specifies the data types defined for the Nupf_EventExposure service.

Table 6.1.6.1-1: Nupf_EventExposure specific Data Types

Data type	Clause defined	Description	Applicability
NotificationData	6.1.6.2.2	The list of NotificationItems
NotificationItem	6.1.6.2.3	Represents a report on one subscribed event
QosMonitoringMeasurement	6.1.6.2.4	QoS Monitoring Measurement information
EventType	6.1.6.3.3	Event Type

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

Table 6.1.6.1-2: Nupf_EventExposure re-used Data Types

Data type	Reference	Comments	Applicability
DateTime	3GPP TS 29.571 [16]	Date time
Dnn	3GPP TS 29.571 [16]	DNN
Gpsi	3GPP TS 29.571 [16]	GPSI
Snssai	3GPP TS 29.571 [16]	S-NSSAI
Uint32	3GPP TS 29.571 [16]	Uint32
MacAddr48	3GPP TS 29.571 [16]	MAC Address
Ipv4Addr	3GPP TS 29.571 [16]	IPv4 address
Ipv6Prefix	3GPP TS 29.571 [16]	IPv6 address prefix

6.1.6.2 Structured data types

6.1.6.2.1 Introduction

This clause defines the structures to be used in resource representations.

6.1.6.2.2 Type: NotificationData

Table 6.1.6.2.2-1: Definition of type NotificationData

Attribute name	Data type	P	Cardinality	Description	Applicability
notificationItems	array(NotificationItem)	M	1..N	The list of NotificationItem, each entry corresponds to a report on one subscribed event.
correlationId	string	C	0..1	The UPF shall include this attribute in the notification if the "Notification Correlation ID" IE was received via N4 interface (see clause 7.5.2.9 of 3GPP TS 29.244 [15])

6.1.6.2.3 Type: NotificationItem

Table 6.1.6.2.3-1: Definition of type NotificationItem

Attribute name	Data type	P	Cardinality	Description	Applicability
eventType	EventType	M	1	The event type of the event for which the notification is generated.
ueIpv4Addr	Ipv4Addr	C	0..1	IPv4 address of the UE (NOTE 1)
ueIpv6Prefix	Ipv6Prefix	C	0..1	IPv6 address prefix of the UE (NOTE 1)
ueMacAddr	MacAddr48	O	0..1	MAC address of the UE.
dnn	Dnn	O	0..1	When present, this attribute indicates the DNN of the PDU session for which the notification is generated.
snssai	Snssai	O	0..1	When present, this attribute indicates the S-NSSAI of the PDU session for which the notification is generated.
gpsi	Gpsi	O	0..1	When present, this attribute indicates the GPSI of the UE for which the notification is generated.
timeStamp	DateTime	M	1	The value represents the UTC time when the information in this report was generated.
startTime	DateTime	O	0..1	When present, this attribute shall provide the timestamp when the information in this report was started
qosMonitoringMeasurement	QosMonitoringMeasurement	C	0..1	This attribute shall be present if eventType is set to "QOS_MONITORING"
NOTE 1: At least one of ueIpv4Addr and ueIpv6Prefix shall be present if IP PDU session is monitored..

6.1.6.2.4 Type: QosMonitoringMeasurement

Table 6.1.6.2.3-1: Definition of type QosMonitoringMeasurement

Attribute name	Data type	P	Cardinality	Description	Applicability
dlPacketDelay	Uint32	O	0..1	When present, the value of this attribute is set to the measured downlink packet delay in millisecond (ms).
ulPacketDelay	Uint32	O	0..1	When present, the value of this attribute is set to the measured uplink packet delay in millisecond (ms).
rtrPacketDelay	Uint32	O	0..1	When present, the value of this attribute is set to the measured round trip packet delay in millisecond (ms).
measureFailure	boolean	C	0..1	This IE shall be present to report packet delay measurement failure. When present, it shall be set to true to indicate the report is sent due to packet delay measurement failure. This IE is named as the "PLMF" flag over PFCP interface. See also clauses 5.24.4.3 and 8.2.171 in 3GPP TS 29.244 [15].

6.1.6.3 Simple data types and enumerations

6.1.6.3.1 Introduction

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

6.1.6.3.2 Simple data types

No specific simple data types are defined in this release.

6.1.6.3.3 Enumeration: EventType

The enumeration EventType represents the type of event to which the service consumer may subscribe to and for which the notification is generated. It shall comply with the provisions defined in table 6.1.5.3.3-1.

Table 6.1.6.3.3-1: Enumeration EventType

Enumeration value	Description	Applicability
"QOS_MONITORING"	QoS Monitoring Measurement

6.1.7 Error Handling

6.1.7.1 General

For the Nupf_EventExposure API, HTTP error responses shall be supported as specified in clause 4.8 of 3GPP TS 29.501 [5]. Protocol errors and application errors specified in table 5.2.7.2-1 of 3GPP TS 29.500 [4] shall be supported for an HTTP method if the corresponding HTTP status codes are specified as mandatory for that HTTP method in table 5.2.7.1-1 of 3GPP TS 29.500 [4].

In addition, the requirements in the following clauses are applicable for the Nupf_EventExposure API.

6.1.7.2 Protocol Errors

No specific procedures for the Nupf_EventExposure service are specified in this release.

6.1.7.3 Application Errors

No application errors for the Nupf_EventExposure service are specified in this release.

6.1.8 Feature negotiation

No specific features for Nupf_EventExposure service are defined in this release.

6.1.9 Security

In this release there is only notification procedure which will be actually invoked, the authorization mechanism does not apply.

Annex A (normative):
OpenAPI specification