5.25 UEId API

29.5223GPP5G SystemNetwork Exposure Function Northbound APIsRelease 18Stage 3TS

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

5.25.1 Introduction

The Nnef_UEId service shall use the UEId API.

The API URI of UEId API shall be:

{apiRoot}/3gpp-ueid/v1

with the following components:

– "apiRoot" is set as described in clause 5.2.4 in 3GPP TS 29.122 [4].

– "apiName" shall be set to "3gpp-ueid".

– "apiVersion" shall be set to "v1" for the current version defined in the present document.

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

5.25.2 Resources

There are no resources defined for this API in this release of the specification.

5.25.3 Custom Operations without associated resources

5.25.3.1 Overview

The structure of the custom operation URIs of the UEId API is shown in Figure 5.25.3.1-1.

Figure 5.25.3.1-1: Custom operation URI structure of the UEId API

Table 5.25.3.1-1 provides an overview of the custom operations and applicable HTTP methods.

Table 5.25.3.1-1: Custom operations without associated resources

Operation name	Custom operation URI	Mapped HTTP method	Description
Retrieve	/retrieve	POST	Request to retrieve AF specific UE ID information.

5.25.3.2 Operation: Retrieve

5.25.3.2.1 Description

The custom operation allows a service consumer to retrieve AF specific UE ID information via the NEF.

Editor’s note: Whether and how user’s consent is needed is FFS and pending SA6 and SA3 feedback.

5.25.3.2.2 Operation Definition

This operation shall support the request and response data structures and response codes specified in table 5.25.3.2.2-1 and table 5.25.3.2.2-2.

Table 5.25.3.2.2-1: Data structures supported by the POST Request Body on this resource

Data type	P	Cardinality	Description
UeIdReq	M	1	Parameters to request to retrieve AF specific UE ID information.

Table 5.25.3.2.2-2: Data structures supported by the POST Response Body on this resource

Data type	P	Cardinality	Response codes	Description
UeIdInfo	M	1	200 OK	The requested AF specific UE ID information was returned successfully.
ProblemDetails	O	0..1	403 Forbidden	If the AF request is not authorized, the NEF shall respond with "403 Forbidden".
ProblemDetails	O	0..1	404 Not Found	If the requested UE ID does not exist or not available in the subscription, the NEF shall respond with "404 Not Found".
n/a			307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
n/a			308 Permanent Redirect	Permanent redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]
NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.25.3.2.2-3: Headers supported by the 307 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI of the resource located in an alternative NEF.

Table 5.25.3.2.2-4: Headers supported by the 308 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative URI of the resource located in an alternative NEF.

5.25.4 Notifications

There are no Notifications defined for this API in this release of the specification.

5.25.5 Data Model

5.25.5.1 General

This clause specifies the application data model supported by the UEId API. Table 5.25.5.1-1 specifies the data types defined for the UEId API.

Table 5.25.5.1-1: UEId service specific Data Types

Data type	Clause defined	Description	Applicability
UeIdReq	5.25.5.2.2	Represents the parameters to requestAF specific UE ID retrieval.
UeIdInfo	5.25.5.2.3	Represents AF specific UE ID information.

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

Table 5.25.5.1-2: Re-used Data Types

Data type	Reference	Comments
Dnn	3GPP TS 29.571 [8]	Identifies a DNN.
ExternalId	3GPP TS 29.122 [4]	Represents an External Identifier.
IpAddr	3GPP TS 29.571 [8]	Identifes an IP address.
MacAddr48	3GPP TS 29.571 [8]	Identifies a MAC address.
MtcProviderInformation	3GPP TS 29.571 [8]	Indicates MTC provider information.
Port	3GPP TS 29.122 [4]	Identifies an application port ID.
Snssai	3GPP TS 29.571 [8]	Identifies the S-NSSAI.
Uinteger	3GPP TS 29.571 [8]	Represents a unsigned integer.

5.25.5.2 Structured data types

5.25.5.2.1 Introduction

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

5.25.5.2.2 Type: UeIdReq

Table 5.25.5.2.2-1: Definition of type UeIdReq

Attribute name	Data type	P	Cardinality	Description	Applicability (NOTE 1)
afId	string	M	1	Represents the identifier of theAF that is sending the request.
appPortId	Port	O	0..1	Identifies an application port ID. See clause 9.2.3.24.4 of 3GPP TS 23.040 [62] for further details.
dnn	Dnn	O	0..1	Identifies a DNN.
ipDomain	string	O	0..1	The IPv4 address domain identifier. The attribute may only be present if the IPv4 address is provided in the "ueIpAddr" attribute.
mtcProviderId	MtcProviderInformation	O	0..1	Indicates MTC provider information.
snssai	Snssai	O	0..1	Identifies an S-NSSAI.
ueIpAddr	IpAddr	C	0..1	Identifies a UE IP Address. (NOTE 2)
ueMacAddr	MacAddr48	C	0..1	Identifies a UE MAC Address. (NOTE 2)
NOTE 1: Properties marked with a feature as defined in clause 5.25.6 are applicable as described in clause 5.2.7 of 3GPP TS 29.122 [4]. If no feature is indicated, the related property is always applied. NOTE 2: One of the "ueIpAddr" attribute or "ueMacAddr" attribute shall be included.

5.25.5.2.3 Type: UeIdInfo

Table 5.25.5.2.3-1: Definition of type UeIdInfo

Attribute name	Data type	P	Cardinality	Description	Applicability
externalId	ExternalId	M	1	Contains the AF specific UE ID in the form of an external identifier uniquely identifying the user.

5.25.5.3 Simple data types and enumerations

5.25.5.3.1 Introduction

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

5.25.5.3.2 Simple data types

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

Table 5.25.5.3.2-1: Simple data types

Type Name	Type Definition	Description	Applicability

5.25.6 Used Features

The table below defines the features applicable to the UEId API. Those features are negotiated as described in clause 5.2.7 of 3GPP TS 29.122 [4].

Table 5.25.6-1: Features used by UEId API

Feature number	Feature Name	Description

5.25.7 Error handling

5.25.7.1 General

HTTP error handling shall be supported as specified in subclause 5.2.6 of 3GPP TS 29.122 [4].

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

5.25.7.2 Protocol Errors

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

5.25.7.3 Application Errors

The application errors defined for the UEId API are listed in table 5.25.7.3-1.

Table 5.25.7.3-1: Application errors

Application Error	HTTP status code	Description
REQUEST_NOT_AUTHORIZED	403 Forbidden	Indicates that the AF specific UE ID retrieval request is not authorized.
UE_ID_NOT_AVAILABLE	404 Not Found	Indicates that the requested AF specific UE ID is not available.
UE_NOT_FOUND	404 Not Found	Indicates that the requested UE address is not found.