6 API Definitions

29.5043GPP5G SystemRelease 18Stage 3TSUnified Data Repository Services

6.1 Nudr_DataRepository Service API

6.1.1 API URI

The Nudr-dr shall use the Nudr-dr API.

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

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

with the following components:

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

– The <apiName> shall be "nudr-dr".

– The <apiVersion> shall be "v2".

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

6.1.2 Usage of HTTP

6.1.2.1 General

Nudr service shall comply with the usage of HTTP/2.0 protocol over Service Based Interfaces. (See Clause 5, 3GPP TS 29.500[7]).

6.1.2.2 HTTP standard headers

6.1.2.2.1 General

The usage of HTTP standard headers shall be supported on Nudr interface as defined in clause 5.2.2 of 3GPP TS 29.500 [7].

6.1.2.2.2 Content type

The following content types shall be supported:

– JSON, as defined in IETF RFC 8259 [11], shall be used as content type of the HTTP bodies specified in the present specification as indicated in clause 5.4 of 3GPP TS 29.500 [7].

– The Problem Details JSON Object (IETF RFC 7807 [17]). The use of the Problem Details JSON object in a HTTP response body shall be signalled by the content type "application/problem+json".

– JSON Merge Patch (IETF RFC 7396 [18]. The use of the JSON Merge Patch format in a HTTP request body shall be signalled by the content type "application/merge-patch+json".

– JSON Patch (IETF RFC 6902 [19]). The use of the JSON Patch format in a HTTP request body shall be signalled by the content type "application/json-patch+json".

6.1.2.2.3 Cache-Control

As described in IETF RFC 7234 [16] clause 5.2, a "Cache-Control" header should be included in HTTP responses carrying a representation of cacheable resources (e.g. SessionManagementSubscriptionData). If it is included, it shall contain a "max-age" value, indicating the amount of time in seconds after which the received response is considered stale.

The "max-age" value shall be configurable by operator policy.

6.1.2.2.4 ETag

As described in IETF RFC 7232 [15] clause 2.3, an "ETag" (entity-tag) header should be included in HTTP responses carrying a representation of cacheable resources (e.g. AccessAndMobilitySubscriptionData) or modifyable resources (e.g. Amf3GppAccessRegistration) to allow an NF Service Consumer performing a conditional GET request with "If-None-Match" header or a conditional POST / PUT / PATCH / DELETE request with "If-Match" header. If it is included, it shall contain a server-generated strong validator, that allows further matching of this value (included in subsequent client requests) with a given resource representation stored in the server or in a cache.

6.1.2.2.5 If-None-Match

As described in IETF RFC 7232 [15] clause 3.2, an NF Service Consumer may issue conditional GET request towards UDR by including an "If-None-Match" header in HTTP requests containing one or several entity tags received in previous responses for the same resource.

6.1.2.2.5a If-Match

As described in IETF RFC 7232 [15] clause 3.1, an NF Service Consumer may issue conditional POST / PUT / PATCH / DELETE request towards UDR by including an "If-Match" header in HTTP requests containing an entity tag received in previous responses for the same resource.

6.1.2.2.6 Last-Modified

As described in IETF RFC 7232 [15] clause 2.2, a "Last-Modified" header should be included in HTTP responses carrying a representation of cacheable resources (e.g. SmfSelectionSubscriptionData) to allow an NF Service Consumer performing a conditional request with "If-Modified-Since" header.

6.1.2.2.7 If-Modified-Since

As described in IETF RFC 7232 [15] clause 3.3, an NF Service Consumer may issue conditional GET request towards UDR, by including an "If-Modified-Since" header in HTTP requests.

6.1.2.2.8 When to Use Entity-Tags and Last-Modified Dates

Both "ETag" and "Last-Modified" headers should be sent in the same HTTP response as stated in IETF RFC 7232 [15] clause 2.4.

NOTE: "ETag" is a stronger validator than "Last-Modified" and is preferred.

If the UDR included an "ETag" header with the resource then a conditional GET request for this resource shall be performed with the "If-None-Match" header, and a POST / PUT / PATCH / DELETE request for this resource shall be performed with the "If-Match" header.

6.1.2.3 HTTP custom headers

6.1.2.3.1 General

The custom HTTP headers applicable to Nudr service are specified in the following clauses.

6.1.2.3.2 3gpp-Sbi-Message-Priority

Nudr interface shall support 3gpp-Sbi-Message-Priority custom header. The header contains the HTTP/2 message priority value. See details in Clause 5.2.3.2.2 of 3GPP TS 29.500 [7].

6.1.2.3.3 3gpp-Sbi-Notification-Correlation

The 3gpp-Sbi-Notification-Correlation header field is used by a NF in a UDR resource create/update/delete request to indicate the subscription context(s) whose notification needs to be disabled when triggered as consequence of a request including this header. Subsequent create/update/delete requests that do not include the 3gpp-Sbi-Notification-Correlation header trigger the corresponding notifications as per currently defined procedures.

This header contains subscription identifier(s), as provided by the UDR during the subscribe operation.

The encoding of the header follows the ABNF as defined in IETF RFC 7230 [12].

3gpp-Sbi-Notification-Correlation = "3gpp-Sbi-Notification-Correlation" ":" 1*(OWS subscriptionId ",")

subscriptionId = token

See clause 3.2.6 of IETF RFC 7230 [12] for the "token" definition.

EXAMPLE: 3gpp-Sbi-Notification-Correlation: subsid123, subsid345.

6.1.3 Resources

6.1.3.1 Overview

Figure 6.1.3.1-1: Resource URI structure of the Nudr_DataRepository 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

SubscriptionData

/subscription-data

none

For sub-level resource names, resource URIs and HTTP methods see 3GPP TS 29.505 [2]

PolicyData

/policy-data

none

For sub-level resource names, resource URIs and HTTP methods see 3GPP TS 29.519 [3]

StructuredDataForExposure

/exposure-data

none

For sub-level resource names, resource URIs and HTTP methods see 3GPP TS 29.519 [3]

ApplicationData

/application-data

none

For sub-level resource names, resource URIs and HTTP methods see 3GPP TS 29.519 [3]

DataRestorationEvents

/data-restoration-events

POST

This is a pseudo operation.

6.1.3.2 SubscriptionData

See 3GPP TS 29.505 [2].

6.1.3.3 PolicyData

See 3GPP TS 29.519 [3].

6.1.3.4 StructuredDataForExposure

See 3GPP TS 29.519 [3].

6.1.3.5 ApplicationData

See 3GPP TS 29.519 [3].

6.1.3.6 Resource: DataRestorationEvents

6.1.3.6.1 Description
6.1.3.6.2 Resource Definition

Resource URI: {apiRoot}/nudr-dr/<apiVersion>/data-restoration-events

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

Table 6.1.3.6.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.6.3 Resource Standard Methods

6.1.3.6.3.1 POST

This method will not be actually invoked.

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

Table 6.1.3.6.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.6.3.1-2 and the response data structures and response codes specified in table 6.1.3.6.3.1-3.

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

Data type

P

Cardinality

Description

Any

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

Data type

P

Cardinality

Response

codes

Description

n/a

6.1.4 Custom Operations without associated resources

In this release of this specification, no custom operations without associated resources are defined for the Nudr_DataRepository Service.

6.1.5 Notifications

6.1.5.1 General

This clause specifies the general mechanism of notifications in the following scenarios:

– notification of changed data which are stored in the UDR;

– notification of data restoration.

The mechanism shall be applicable to the data specified in 3GPP TS 29.505[2] and 3GPP TS 29.519[3].

6.1.5.2 Data Change Notification

The POST method shall be used for Data Change Notifications and the URI shall be as provided during the subscription procedure.

Resource URI: {callbackReference}

Support of POST request data structures should contain the object of changed data and conditionally the URI of original Callback reference, which is received from the original subscribed NF.

6.1.5.3 Data Restoration Notification

The POST method shall be used to inform the NF Service Consumer about a potential data-loss event occurred at the UDR, and the callback URI shall be dynamically discovered by UDR by querying NRF for a default notification URI.

Resource URI: {dataRestorationCallbackUri}

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

Table 6.1.5.3-1: URI query parameters supported by the POST method

Name

Data type

P

Cardinality

Description

n/a

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

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

Data type

P

Cardinality

Description

DataRestorationNotification

M

1

Contains identifiers representing those UEs potentially affected by a data-loss event at the UDR.

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

Data type

P

Cardinality

Response

codes

Description

n/a

204 No Content

Upon success, an empty response body shall be returned.

RedirectResponse

O

0..1

307 Temporary Redirect

Temporary redirection. The response shall include a Location header field containing a different URI. The URI shall be an alternative URI of the resource located on an alternative service instance within the same NF or NF (service) set.

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

Permanent redirection. The response shall include a Location header field containing a different URI. The URI shall be an alternative URI of the resource located on an alternative service instance within the same NF or NF (service) set.

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.

ProblemDetails

O

0..1

404 Not Found

The "cause" attribute may be used to indicate one of the following application errors:

– CONTEXT_NOT_FOUND

NOTE: In addition, common data structures as listed in table 5.2.7.1-1 of 3GPP TS 29.500 [7] are supported.

Table 6.1.5.3-4: Headers supported by the 307 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

Contains the Callback URI of the target NF Service Consumer (e.g. UDM) to which the request is redirected

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

Table 6.1.5.3-5: Headers supported by the 308 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

Contains the Callback URI of the target NF Service Consumer (e.g. AMF) to which the request is redirected

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

6.1.5a Data Model

6.1.5a.1 General

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

Table 6.1.5a.1-1 specifies the data types defined for the Nudr_DataRepository API.

Table 6.1.5a.1-1: Nudr_DataRepository specific Data Types

Data type

Clause defined

Description

DataRestorationNotification

6.2.5a.2.2

Contains identities representing those UEs potentially affected by a data-loss event at the UDR

Table 6.1.5a.1-2 specifies data types re-used by the Nudr_DataRepository service-based interface protocol from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the Nudr_DataRepository service-based interface.

Table 6.1.5a.1-2: Nudr_DataRepository re-used Data Types

Data type

Reference

Comments

Dnn

3GPP TS 29.571 [10]

Data Network Name with Network Identifier only.

Snssai

3GPP TS 29.571 [10]

Single NSSAI

NfGroupId

3GPP TS 29.571 [10]

NF Group ID

IdentityRange

3GPP TS 29.510 [14]

Identity Range

SupiRange

3GPP TS 29.510 [14]

SUPI Range

6.1.5a.2 Structured data types

6.1.5a.2.1 Introduction

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

6.1.5a.2.2 Type: DataRestorationNotification

Table 6.2.5a.2.2-1: Definition of type DataRestorationNotification

Attribute name

Data type

P

Cardinality

Description

supiRanges

array(SupiRange)

O

1..N

If present, it contains the list of SUPIs potentially subject to a data-loss event at the UDR.

gpsiRanges

array(IdentityRange)

O

1..N

If present, it contains the list of GPSIs potentially subject to a data-loss event at the UDR.

resetIds

array(string)

O

1..N

If present, it contains the list of Reset-IDs of those UEs potentially subject to a data-loss event at the UDR.

sNssaiList

array(Snssai)

O

1..N

If present, it contains the list of slices (S-NSSAIs) potentially subject to a data-loss event at the UDR.

dnnList

array(Dnn)

O

1..N

If present, it contains the list of DNNs potentially subject to a data-loss event at the UDR.

lastReplicationTime

DateTime

O

0..1

If present, it contains the timestamp of the most recent instant when the data was assumed to be consistent at UDR (i.e. the potential data loss event at UDR did not occur before this instant).

recoveryTime

DateTime

O

0..1

If present, it contains the timestamp of the instant when the potential data loss event was recovered at UDR (i.e. all data records stored by UDR after this time are assumed to be consistent).

udrGroupId

NfGroupId

O

0..1

If present, it contains the ID of the UDR Group whose UEs have been potentially subject to a data loss event at the UDR.

6.1.6 Error Handling

Table 6.1.6-1 lists common response body data structures used within the nudr-dr (Nudr_DataRepository) API

Table 6.1.6-1: Common Response Body Data Structures

Data type

P

Cardinality

Response

codes

Description

ProblemDetails

O

0..1

4xx, 5xx responses

For error status codes, the UDR may provide detailed information.

NOTE: In addition common data structures as defined in 3GPP TS 29.500 [7] are supported.

The "ProblemDetails" data structure may contain a "cause" attribute to indicate the application error, see 3GPP TS 29.571 [10]. The values for "cause" attribute are defined in table 6.1.6-2.

Table 6.1.6-2: Application Errors

Application Error

HTTP status code

Description

NF_TYPE_NOT_ALLOWED

403 Forbidden

The target data set is not permitted to access for the NF type of the NF consumer.

UNSUPPORTED_MONITORED_URI

501 Not Implemented

The subscribe service operation is not able to be implemented due to invalid resource URI to be monitored).

USER_NOT_FOUND

404 Not Found

The user indicated in the HTTP/2 request does not exist in the UDR.

DATA_NOT_FOUND

404 Not Found

The data indicated in the HTTP/2 request is unavailable in the UDR.

INCORRECT_CONDITIONAL_GET_REQUEST

412 Precondition Failed

One or more conditions given in the request header fields evaluated to false when tested in the UDR.

UNPROCESSABLE_REQUEST

422 Unprocessable Entity

The request cannot be procesed due to semantic errors when trying to process a patch method.

DATABASE INCONSISTENCY

500 Internal Server Error

Requested data cannot be returned due to database inconsistency

RESOURCE_TEMP_MOVED

307 Temporary Redirect

The resource is unavailable in the current target URI but can be temporarily found in an alternative URI.

RESOURCE_MOVED

308 Permanent Redirect

The resource is unavailable in the current target URI but can be permanently found in an alternative URI.

GROUP_IDENTIFIER_NOT_FOUND

404 Not Found

The group identifier does not exist.

MODIFICATION_NOT_ALLOWED

403 Forbidden

Modification of the target resource representation is not permitted.

PLMN_NOT_FOUND

404 Not Found

The ‘servingPlmnId’ indicated in the HTTP/2 query is unavailable in the UDR. This status code is also used when ‘servingPlmnId’ path variable contains SNPN ID, see Table 5.2.3.2-1 in 3GPP TS 29.505 [2].

NOTE: The error codes shall apply to both 3GPP TS 29.505 [2] and 3GPP TS 29.519 [3]. In addition error codes shall comply with the definition in clause 5.2.7.2 of 3GPP TS 29.500 [7].

6.1.7 Security

As indicated in 3GPP TS 33.501 [12], the access to the Nudr_DataRepository API may be authorized by means of the OAuth2 protocol (see IETF RFC 6749 [13]), using the "Client Credentials" authorization grant, where the NRF (see 3GPP TS 29.510 [14]) plays the role of the authorization server.

If Oauth2 authorization is used, an NF Service Consumer, prior to consuming services offered by the Nudr_DataRepository API, shall obtain a "token" from the authorization server, by invoking the Access Token Request service, as described in 3GPP TS 29.510 [14], clause 5.4.2.2.

NOTE: When multiple NRFs are deployed in a network, the NRF used as authorization server is the same NRF that the NF Service Consumer used for discovering the Nudr_DataRepository service.

The Nudr_DataRepository API defines the following scopes for OAuth2 authorization:

Table 6.1.7-1: Oauth2 scopes defined in Nudr_DataRepository API

Scope

Description

"nudr-dr"

Access to the Nudr DataRepository API

"nudr-dr:subscription-data"

Access to the SubscriptionData data set.

"nudr-dr:subscription-data:authentication-subscription:read"

Access to read the AuthenticationSubscription resource of the SubscriptionData data set.

"nudr-dr:subscription-data:authentication-subscription:modify"

Access to update the AuthenticationSubscription resource of the SubscriptionData data set.

"nudr-dr:subscription-data:registrations:write"

Write access to NF registration resources of the SubscriptionData data set.

"nudr-dr:policy-data"

Access to the PolicyData data set.

"nudr-dr:policy-data:ues:read"

Access to read the UEs resource.

"nudr-dr:policy-data:ues:am-data:read"

Access to read the UEs Access and Mobility Policy data.

"nudr-dr:policy-data:ues:ue-policy-set:read"

Access to read the UEs Policy Set data.

"nudr-dr:policy-data:ues:ue-policy-set:create"

Access to create the UEs Policy Set data.

"nudr-dr:policy-data:ues:ue-policy-set:modify"

Access to update the UEs Policy Set data.

"nudr-dr:policy-data:ues:sm-data:read"

Access to read the UEs Session Management policy data.

"nudr-dr:policy-data:ues:sm-data:modify"

Access to update the UEs Session Management policy data.

"nudr-dr:policy-data:ues:sm-data:create"

Access to create the UEs Session Management policy data.

"nudr-dr:policy-data:sponsor-connectivity-data:read"

Access to read the sponsored connectivity data.

"nudr-dr:policy-data:bdt-data:read"

Access to read the BDT data resource.

"nudr-dr:policy-data:bdt-data:create"

Access to create the BDT data resource.

"nudr-dr:policy-data:bdt-data:modify"

Access to update the BDT data resource.

"nudr-dr:policy-data:subs-to-notify:create"

Access to create Subscriptions resources.

"nudr-dr:policy-data:subs-to-notify:modify"

Access to update Subscriptions resources.

"nudr-dr:policy-data:ues:operator-specific-data:read"

Access to read the UEs operator specific policy data.

"nudr-dr:policy-data:ues:operator-specific-data:modify"

Access to update the UEs operator specific policy data.

"nudr-dr:policy-data:ues:operator-specific-data:create"

Access to create the UEs operator specific policy data.

"nudr-dr:policy-data:slice-control-data:read"

Access to read Slice specific Policy Control Data.

"nudr-dr:policy-data:slice-control-data:modify"

Access to update Slice specific Policy Control Data.

"nudr-dr:exposure-data"

Access to the ExposureData data set.

"nudr-dr:exposure-data:access-and-mobility-data:create"

Access to create Access and Mobility data.

"nudr-dr:exposure-data:access-and-mobility-data:read"

Access to read Access and Mobility data.

"nudr-dr:exposure-data:access-and-mobility-data:modify"

Access to update Access and Mobility data.

"nudr-dr:exposure-data:session-management-data:create"

Access to create Session Management data.

"nudr-dr:exposure-data:session-management-data:read"

Access to read Session Management data.

"nudr-dr:exposure-data:session-management-data:modify"

Access to update Session Management data.

"nudr-dr:exposure-data:subs-to-notify:create"

Access to create Subscriptions resources.

"nudr-dr:exposure-data:subs-to-notify:modify"

Access to update Subscriptions resources.

"nudr-dr:application-data"

Access to the ApplicationData data set.

"nudr-dr:application-data:pfds:read"

Access to read PFDData.

"nudr-dr:application-data:pfds:modify"

Access to update PFDData.

"nudr-dr:application-data:pfds:create"

Access to create PFDData.

"nudr-dr:application-data:influence-data:read"

Access to read Traffic Influence Data.

"nudr-dr:application-data:influence-data:create"

Access to create Traffic Influence Data.

"nudr-dr:application-data:influence-data:modify"

Access to update Traffic Influence Data.

"nudr-dr:application-data:influence-data:subscriptions:create"

Access to create Traffic Influence Data Subscriptions.

"nudr-dr:application-data:influence-data:subscriptions:read"

Access to read Traffic Influence Data Subscriptions.

"nudr-dr:application-data:influence-data:subscriptions:modify"

Access to update Traffic Influence Data Subscriptions.

"nudr-dr:application-data:bdt-policy-data:read"

Access to read BDT Policy Data.

"nudr-dr:application-data:bdt-policy-data:create"

Access to create BDT Policy Data.

"nudr-dr:application-data:bdt-policy-data:modify"

Access to update BDT Policy Data.

"nudr-dr:application-data:iptv-config-data:read"

Access to read IPTV Configuration Data.

"nudr-dr:application-data:iptv-config-data:create"

Access to create IPTV Configuration Data.

"nudr-dr:application-data:iptv-config-data:modify"

Access to update IPTV Configuration Data.

"nudr-dr:application-data:service-param-data:read"

Access to read Service Parameter Data.

"nudr-dr:application-data:service-param-data:create"

Access to create Service Parameter Data.

"nudr-dr:application-data:service-param-data:modify"

Access to update Service Parameter Data.

"nudr-dr:application-data:am-influence-data:read"

Access to read AM Influence Data.

"nudr-dr:application-data:am-influence-data:create"

Access to create AM Influence Data.

"nudr-dr:application-data:am-influence-data:modify"

Access to update AM Influence Data.

"nudr-dr:application-data:subs-to-notify:create"

Access to create Subscriptions resources.

"nudr-dr:application-data:subs-to-notify:read"

Access to read Subscriptions resources.

"nudr-dr:application-data:subs-to-notify:modify"

Access to update Subscriptions resources.

"nudr-dr:application-data:eas-deploy-data:read"

Access to read EAS Deployment Information Data.

"nudr-dr:application-data:eas-deploy-data:create"

Access to create EAS Deployment Information Data.

"nudr-dr:application-data:eas-deploy-data:modify"

Access to update EAS Deployment Information Data.

6.1.8 Feature negotiation

The optional features in table 6.1.8-1 are defined for the Nudr_DataRepository API. They shall be negotiated using the extensibility mechanism defined in clause 6.6 of 3GPP TS 29.500 [7].

Table 6.1.8-1: Supported Features

Feature number

Feature Name

Description

1

ResourceRemovalNotificationPolicyData

This feature indicates the support of the complete removal of a Policy Data resource.

2

ResourceNotificationExposureDataFix

This feature indicates the support of corrections to Notifications of data changes in the Exposure Data resource.

3

DomainNameProtocol

This feature supports the additional protocol matching condition for the domain name in PFD data.

4

EnhancedBackgroundDataTransfer

This feature indicates the support of applying the Background Data Transfer Policy to a future PDU session requested by the AF for Policy Data resource and Application Data resource as defined in 3GPP TS 29.519 [3]. This feature requires the support of SessionManagementPolicyDataPatch feature to update Background Data Transfer data within the Session Management Policy Data.

5

MacAddressRange

This feature indicates the support of a set of MAC addresses with a specific range for the traffic filter in the application data resource as specified in 3GPP TS 29.519 [3].

6

MultiTemporalCondition

This feature indicates the support of multiple temporal validity conditions in the Traffic Influence Data resource as specified in 3GPP TS 29.519 [3].

7

PatchReport

If some of the modifications included in the PATCH request are not successfully implemented, the UDM reports the result of PATCH request execution to the consumer. See clause 5.2.7.2 of 3GPP TS 29.500 [7].

8

URLLC

This feature indicates support of Ultra Reliable Low Latency Communication (URLLC) requirements, i.e. AF application relocation and UE address(es) preservation in the Application Data resource as specified in 3GPP TS 29.519 [3].

9

SessionManagementPolicyDataPatch

This feature indicates the support of the HTTP PATCH method to update the session management policy data defined in a Policy Data resource as specified in 3GPP TS 29.519 [3].

10

ConditionalSubscriptionwithPartialNotification

This feature indicates the support of subscription to notification of resource data changes conditioned to the change occurs in a fragment of the resource. It applies for Policy Data resources as specified in 3GPP TS 29.519 [3].

11

EnhancedInfluDataNotification

This feature indicates the support of enhancement of data change Notifications in the Influence Data resource as specified in 3GPP TS 29.519 [3].

12

PerUePerSnAuthStatus

This feature indicates the support of the Individual authentication status per UE per serving network as specified in 3GPP TS 29.505 [2].

13

OpSpecDataMapNotification

This feature indicates the support of the notification of data changes in the OperatorSpecificData resource by including the complete map of Operator Specific Data Containers. It applies to Policy Data resources as specified in 3GPP TS 29.519 [3].

14

PlmnSmPolicyData

This feature indicates the support of a resource in the policy data which represents Session Management Policy Data per PLMN. It applies for Policy Data resources as specified in 3GPP TS 29.519 [3].

15

OSDResource_Create_Delete

This feature indicates the support of the creation and the removal of the OperatorSpecificData resource by a Policy Data NF service consumer. It applies to Policy Data resources as specified in 3GPP TS 29.519 [3].

16

AF_latency

This feature indicates the support for Edge relocation considering user plane latency. It applies for Influence Data resource as specified in 3GPP TS 29.519 [3].

17

CHFsetSupport

This feature indicates the support of CHF redundancy and failover mechanisms based on CHF instance availability within a CHF Set, (i.e. secondary CHF address may be omitted). It applies to Policy Data resources as specified in 3GPP TS 29.519 [3].

18

ConditionalSubscriptionWithExcludeNotification

This feature indicates the support in the subscription to notification of data changes of the indication of the properties whose changes do not trigger a notification. It applies to Policy Data resources as specified in 3GPP TS 29.519 [3]. It requires the support of OpSpecDataMapNotification feature

19

ProSe

This feature indicates the support of UE 5G ProSe policies and subscription information. It applies for Policy Data resources as specified in 3GPP TS 29.519 [3].

20

NSAC

This feature indicates the support of NSAC (Network Slice Admission Control) related policy subscription information. It applies to Policy Data resources as specified in 3GPP TS 29.519 [3].

21

UESubDataSetRetrieve

This feature indicates the support of the UE Subscription Data Sets Retrieve as specified in clause 5.2.47 of 3GPP TS 29.505 [2].

22

SharedSmSubsData

This feature indicates the support of shared Session Management Subscription Data. If the NF consumer (UDM) does not support this feature, the UDR shall not take the alternative to include extendedSmSubsData in SmSubsData.
It applies to Subscription Data resources as specified in 3GPP TS 29.505 [2]

23

DeliveryOutcome

This feature indicates the support of functionality to allow PCF notifications about the outcome of the UE Policy delivery related to the invocation of AF provisioned service parameters as specified in 3GPP TS 29.519 [3].

24

AfGuideURSP

This feature indicates the support of Application guidance for URSP determination related application data as specified in 3GPP TS 29.519 [3].

25

EasDeployment

This feature indicates the support of EAS Deployment Information Data and Subscription related application data as specified in 3GPP TS 29.519 [3].

26

DCAMP

This feature indicates the support of DCAMP related application data. It applies to Application Data resources as specified in 3GPP TS 29.519 [3].

27

FilterAnyUE

This feature indicates the support of queries and subscriptions to service parameter data resource filtered by the any UE indication as specified in 3GPP TS 29.519 [3].

28

SimultConnectivity

This feature indicates the support of temporary simultaneously connectivity at edge relocation. It applies for Influence Data resource as specified in 3GPP TS 29.519 [3].

29

EeSubscriptionExt

This feature indicates the support of handling EE subscription data along with associated subscription resources as specified in 3GPP TS 29.505 [2].

30

PeiResource

This feature indicates the support of storing PEI in the PeiInfo resource as specified in 3GPP TS 29.505 [2].

31

ImmediateReportPcc

This feature indicates support of ImmediateReport within a PolicyDataSubscription in 3GPP TS 29.519 [3]. When a UDR consumer detects that the UDR supports the ImmediateReportPcc feature, it can indicate an immediateReport flag when invoking the Subscribe service operation. If the UDR receives the ImmediateReport flag in the received Subscribe service operation request, it shall return the resource’s representation(s) of the monitored resource(s) in the service operation response body.

32

ImmediateReport

This feature indicates support of ImmediateReport within an SubscriptionDataSubscription in 3GPP TS 29.505 [2]. When a UDR consumer detects that the UDR supports the ImmediateReport feature, it can indicate an immediateReport flag when invoking the Subscribe service operation. If the UDR receives the ImmediateReport flag in the received Subscribe service operation request, it shall return the resource’s representation(s) of the monitored resource(s) in the service operation response body.

6.2 Nudr_GroupIDmap Service API

6.2.1 API URI

URIs of this API shall have the following root:

{apiRoot}/<apiName>/<apiVersion>

where "apiRoot" is defined in clause 4.4.1 of 3GPP TS 29.501 [8], the "apiName" shall be set to "nudr-group-id-map" and the "apiVersion" shall be set to "v1" for the current version of this specification.

6.2.2 Usage of HTTP

6.2.2.1 General

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

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

HTTP messages and bodies for the Nudr_GroupIDmap service shall comply with the OpenAPI [21] specification contained in Annex A3.

6.2.2.2 HTTP standard headers

6.2.2.2.1 General

The usage of HTTP standard headers shall be supported on Nudr interface as defined in clause 5.2.2 of 3GPP TS 29.500 [7].

6.2.2.2.2 Content type

The following content types shall be supported:

– JSON, as defined in IETF RFC 8259 [11], shall be used as content type of the HTTP bodies specified in the present specification as indicated in clause 5.4 of 3GPP TS 29.500 [7].

– The Problem Details JSON Object (IETF RFC 7807 [17]). The use of the Problem Details JSON object in a HTTP response body shall be signalled by the content type "application/problem+json".

6.2.2.2.3 Cache-Control

As described in IETF RFC 7234 [16] clause 5.2, a "Cache-Control" header should be included in HTTP responses carrying a representation of cacheable resources. If it is included, it shall contain a "max-age" value, indicating the amount of time in seconds after which the received response is considered stale.

The "max-age" value shall be configurable by operator policy.

6.2.2.2.4 ETag

As described in IETF RFC 7232 [15] clause 2.3, an "ETag" (entity-tag) header should be included in HTTP responses carrying a representation of cacheable resources to allow an NF Service Consumer performing a conditional GET request with "If-None-Match" header. If it is included, it shall contain a server-generated strong validator, that allows further matching of this value (included in subsequent client requests) with a given resource representation stored in the server or in a cache.

6.2.2.2.5 If-None-Match

As described in IETF RFC 7232 [15] clause 3.2, an NF Service Consumer may issue conditional GET request towards UDR by including an "If-None-Match" header in HTTP requests containing one or several entity tags received in previous responses for the same resource.

6.2.2.2.6 Last-Modified

As described in IETF RFC 7232 [15] clause 2.2, a "Last-Modified" header should be included in HTTP responses carrying a representation of cacheable resources (e.g. SmfSelectionSubscriptionData) to allow an NF Service Consumer performing a conditional request with "If-Modified-Since" header.

6.2.2.2.7 If-Modified-Since

As described in IETF RFC 7232 [15] clause 3.3, an NF Service Consumer may issue conditional GET request towards UDR, by including an "If-Modified-Since" header in HTTP requests.

6.2.2.2.8 When to Use Entity-Tags and Last-Modified Dates

Both "ETag" and "Last-Modified" headers should be sent in the same HTTP response as stated in IETF RFC 7232 [15] clause 2.4.

NOTE: "ETag" is a stronger validator than "Last-Modified" and is preferred.

If the UDR included an "ETag" header with the resource then a conditional GET request for this resource shall be performed with the "If-None-Match" header.

6.2.2.3 HTTP custom headers

6.2.2.3.1 General

In this release of this specification, no custom headers specific to the Nudr_GroupIDmap service are defined. For 3GPP specific HTTP custom headers used across all service-based interfaces, see clause 5.2.3 of 3GPP TS 29.500 [7].

6.2.3 Resources

6.2.3.1 Overview

Figure 6.2.3.1-1: Resource URI structure of the nudr-group-id-map API

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

Table 6.2.3.1-1: Resources and methods overview

Resource name

Resource URI

HTTP method

Description

NfGroupIds

/nf-group-ids

GET

6.2.3.2 Resource NfGroupIds

6.2.3.2.1 Description

This resource represents the NF-Group IDs for a subscriber.

6.2.3.2.2 Resource Definition

Resource URI: {apiRoot}/nudr-group-id-map/<apiVersion>/nf-group-ids

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

Table 6.2.3.2.2-1: Resource URI variables for this resource

Name

Definition

apiRoot

See clause 6.2.1

6.2.3.2.3 Resource Standard Methods

6.2.3.2.3.1 GET

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

Table 6.2.3.2.3.1-1: URI query parameters supported by the GET method on this resource

Name

Data type

P

Cardinality

Description

nf-type

array(NFType)

M

1..N

see 3GPP TS 29.510 [14]

subscriberId

SubscriberId

M

1

Represents the Subscription Identifier SUPI or GPSI or IMPI or IMPU (see 3GPP TS 23.501 [4] clause 5.9.2 and clause 5.9.8)
pattern: ^(imsi-[0-9]{5,15}|nai-.+|msisdn-[0-9]{5,15}|extid-[^@]+@[^@]+|impi-.+|impu-.+|.+)$

NOTE: The format of the query parameter subscriberId is in line with the yaml and thus does not follow the lower-with-hyphen format specified in 3GPP TS 29.501 [8].

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

Table 6.2.3.2.3.1-2: Data structures supported by the GET Request Body on this resource

Data type

P

Cardinality

Description

n/a

Table 6.2.3.2.3.1-3: Data structures supported by the GET Response Body on this resource

Data type

P

Cardinality

Response

codes

Description

NfGroupIdMapResult

M

1

200 OK

Upon success, a response body containing the NF-Group IDs for the requested NF types shall be returned.

ProblemDetails

O

0..1

404 Not Found

The "cause" attribute may be set to one of the following application errors:

– USER_NOT_FOUND

NOTE: In addition common data structures as listed in table 5.2.7.1-1 of 3GPP TS 29.500 are supported.

6.2.4 Custom Operations without associated resources

In this release of this specification, no custom operations without associated resources are defined for the Nudr_GroupIDmap Service.

6.2.5 Notifications

In this release of this specification, no notifications are defined for the Nudr_GroupIDmap Service.

6.2.6 Data Model

6.2.6.1 General

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

Table 6.2.6.1-1 specifies the structured data types defined for the Nudr_GroupIDmap service API. For simple data types defined for the Nudr_GroupIDmap service API see table 6.2.6.3.2-1.

Table 6.2.6.1-1: Nudr_GroupIDmap specific Data Types

Data type

Clause defined

Description

NfGroupIdMapResult

6.2.6.2.2

NF-Group IDs for the requested NF types

SubscriberId

6.2.6.3.2

Represents the Subscription Identifier SUPI or GPSI or IMPI or IMPU

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

Table 6.2.6.1-2: Nudr_GroupIDmap re-used Data Types

Data type

Reference

Comments

ProblemDetails

3GPP TS 29.571 [10]

Common data type used in response bodies

NFType

3GPP TS 29.510 [14]

NfGroupId

3GPP TS 29.571 [10]

6.2.6.2 Structured data types

6.2.6.2.1 Introduction

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

6.2.6.2.2 Type: NfGroupIdMapResult

Table 6.2.6.2.2-1: Definition of type NfGroupIdMapResult

Attribute name

Data type

P

Cardinality

Description

nfGroupIDs

map(NfGroupId)

M

1..N

A map (list of key-value pairs where NFType serves as key) of NFGroupIds

6.2.6.3 Simple data types and enumerations

6.2.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.2.6.3.2 Simple data types

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

Table 6.2.6.3.2-1: Simple data types

Type Name

Type Definition

Description

SubscriberId

string

Pattern: ^(imsi-[0-9]{5,15}|nai-.+|msisdn-[0-9]{5,15}|extid-[^@]+@[^@]+|impi-.+|impu-.+|.+)$

6.2.7 Error Handling

6.2.7.1 General

HTTP error handling shall be supported as specified in clause 5.2.4 of 3GPP TS 29.500 [7].

6.2.7.2 Protocol Errors

Protocol errors handling shall be supported as specified in clause 5.2.7 of 3GPP TS 29.500 [7].

6.2.7.3 Application Errors

The common application errors defined in the Table 5.2.7.2-1 in 3GPP TS 29.500 [7] may also be used for the Nudr_GroupIDmap service. The following application errors listed in Table 6.2.7.3-1 are specific for the Nudr_GroupIDmap service.

Table 6.2.7.3-1: Application errors

Application Error

HTTP status code

Description

USER_NOT_FOUND

404 Not Found

The user does not exist in the HPLMN

6.2.8 Security

As indicated in 3GPP TS 33.501 [12], the access to the Nudr_GroupIDmap API may be authorized by means of the OAuth2 protocol (see IETF RFC 6749 [13]), using the "Client Credentials" authorization grant, where the NRF (see 3GPP TS 29.510 [14]) plays the role of the authorization server.

If Oauth2 authorization is used, an NF Service Consumer, prior to consuming services offered by the Nudr_GroupIDmap API, shall obtain a "token" from the authorization server, by invoking the Access Token Request service, as described in 3GPP TS 29.510 [14], clause 5.4.2.2.

NOTE: When multiple NRFs are deployed in a network, the NRF used as authorization server is the same NRF that the NF Service Consumer used for discovering the Nudr_GroupIDmap service.

The Nudr_GroupIDmap API defines scopes for OAuth2 authorization as specified in 3GPP TS 33.501 [12]; it defines a single scope consisting on the name of the service (i.e., "nudr-group-id-map"), and it does not define any additional scopes at resource or operation level.

6.2.9 Feature Negotiation

The optional features in table 6.2.9-1 are defined for the Nudr_GroupIDmap API. They shall be negotiated using the extensibility mechanism defined in clause 6.6 of 3GPP TS 29.500 [7].

Table 6.2.9-1: Supported Features

Feature number

Feature Name

Description

Annex A (normative):
OpenAPI specification