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. |
|
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) |
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