5.8 ApplyingBdtPolicy API

29.5223GPP5G SystemNetwork Exposure Function Northbound APIsRelease 18Stage 3TS

5.8.1 Resources

5.8.1.1 Overview

All resource URIs of this API should have the following root:

{apiRoot}/3gpp-applying-bdt-policy/v1

"apiRoot" is set as described in clause 5.2.4 in 3GPP TS 29.122 [4]. "apiName" shall be set to "3gpp-applying-bdt-policy" and "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.

This clause describes the structure for the Resource URIs as shown in figure 5.8.1.1-1 and the resources and HTTP methods used for the ApplyingBdtPolicy API.

Figure 5.8.1.1-1: Resource URI structure of the ApplyingBdtPolicy API

Table 5.8.1.1-1 provides an overview of the resources and HTTP methods applicable for the ApplyingBdtPolicy API.

Table 5.8.1.1-1: Resources and methods overview

Resource name	Resource URI	HTTP method	Description
Applied BDT Policy Subscriptions	/{afId}/subscriptions	GET	Read all applied BDT policy subscriptions for a given AF.
		POST	Create a new applied policy subscription.
Individual Applied BDT Policy Subscription	/{afId}/subscriptions/{subscriptionId}	GET	Read an applied BDT policy subscription.
		PATCH	Modify BDT Reference ID of an existing subscription to a BDT policy.
		DELETE	Delete an applied BDT policy subscription

5.8.1.2 Resource: Applied BDT Policy Subscriptions

5.8.1.2.1 Introduction

This resource allows a AF to read all applied BDT policy subscriptions for the given AF.

5.8.1.2.2 Resource Definition

Resource URI: {apiRoot}/3gpp-applying-bdt-policy/v1/{afId}/subscriptions

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

Table 5.8.1.2.2-1: Resource URI variables for this resource

Name	Data type	Definition
apiRoot	string	Clause 5.2.4 of 3GPP TS 29.122 [4].
afId	string	Identifier of the AF.

5.8.1.2.3 Resource Methods

5.8.1.2.3.1 General

The following clauses specify the resource methods supported by the resource as described in clause 5.8.1.2.2.

5.8.1.2.3.2 GET

The GET method allows to read all active applied BDT policy subscriptions for a given AF. The AF shall initiate the HTTP GET request message and the NEF shall respond to the message.

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

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

Name	Data type	P	Cardinality	Description
N/A

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

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

Data type	P	Cardinality	Description
N/A

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

Data type	P	Cardinality	Response codes	Description
array(AppliedBdtPolicy)	M	0..N	200 OK	The applied BDT Policy subscriptions for the AF in the request URI are returned.
N/A			307 Temporary Redirect	Temporary redirection, during subscription retrieval. 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, during subscription retrieval. 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 GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.8.1.2.3.2-4: 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.8.1.2.3.2-5: 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.8.1.2.3.3 POST

The POST method creates an applied BDT policy subscription for a given AF. The AF shall initiate the HTTP POST request message and the NEF shall respond to the message. The NEF shall construct the URI of the created resource.

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

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

Data type	P	Cardinality	Description
AppliedBdtPolicy	M	1	Parameters to create a subscription of the applied BDT policy.

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

Data type	P	Cardinality	Response codes	Description
AppliedBdtPolicy	M	1	201 Created	The subscription was created successfully. The URI of the created resource shall be returned in the "Location" HTTP header.
NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.8.1.2.3.3-3: Headers supported by the 201 Response Code on this resource

Name	Data type	P	Cardinality	Description
Location	string	M	1	Contains the URI of the newly created resource, according to the structure: {apiRoot}/3gpp-applying-bdt-policy/v1/{afId}/subscriptions/{SubscriptionId}

5.8.1.3 Resource: Individual Applied BDT Policy Subscription

5.8.1.3.1 Introduction

This resource allows a AF to read or delete an active subscription of applied BDT policy.

5.8.1.3.2 Resource Definition

Resource URI: {apiRoot}/3gpp-applying-bdt-policy/v1/{afId}/subscriptions/{subscriptionId}

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

Table 5.8.1.3.2-1: Resource URI variables for this resource

Name	Data type	Definition
apiRoot	string	Clause 5.2.4 of 3GPP TS 29.122 [4].
afId	string	Identifier of the AF.
subscriptionId	string	Identifier of the subscription resource.

5.8.1.3.3 Resource Methods

5.8.1.3.3.1 General

The following clauses specify the resource methods supported by the resource as described in clause 5.8.1.3.2.

5.8.1.3.3.2 GET

The GET method allows to read the active applied BDT policy for a given AF and subscription Id. The AF shall initiate the HTTP GET request message and the NEF shall respond to the message.

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

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

Name	Data type	P	Cardinality	Description
N/A

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

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

Data type	P	Cardinality	Description
N/A

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

Data type	P	Cardinality	Response codes	Description
AppliedBdtPolicy	M	1	200 OK	The subscription information for the AF in the request URI are returned.
N/A			307 Temporary Redirect	Temporary redirection, during subscription retrieval. 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, during subscription retrieval. 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 GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.8.1.3.3.2-4: 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.8.1.3.3.2-5: 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.8.1.3.3.3 PATCH

The PATCH method allows to change some properties of an existing applied BDT policy subscription. The AF shall initiate the HTTP PATCH request message and the NEF shall respond to the message.

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

Table 5.8.1.3.3.3-1: Data structures supported by the PATCH Request Body on this resource

Data type	P	Cardinality	Description
AppliedBdtPolicyPatch	M	1	Partial update of a subscription to applying BDT policy subscritpion.

Table 5.8.1.3.3.3-2: Data structures supported by the PATCH Response Body on this resource

Data type	P	Cardinality	Response codes	Description
AppliedBdtPolicy	M	1	200 OK	The subscription was modified successfully.
n/a			204 No Content	The subscription was modified successfully.
N/A			307 Temporary Redirect	Temporary redirection, during subscription modification. 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, during subscription modification. 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 PATCH method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.8.1.3.3.3-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.8.1.3.3.3-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.8.1.3.3.4 DELETE

The DELETE method deletes an existing applied BDT policy subscription for a given AF. The AF shall initiate the HTTP DELETE request message and the NEF shall respond to the message.

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

Table 5.8.1.3.3.4-1: URI query parameters supported by the DELETE method on this resource

Name	Data type	P	Cardinality	Description
N/A

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

Table 5.8.1.3.3.4-2: Data structures supported by the DELETE Request Body on this resource

Data type	P	Cardinality	Description
N/A

Table 5.8.1.3.3.4-3: Data structures supported by the DELETE Response Body on this resource

Data type	P	Cardinality	Response codes	Description
N/A			204 No Content	The subscription was terminated successfully.
N/A			307 Temporary Redirect	Temporary redirection, during subscription termination. 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, during subscription termination. 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 DELETE method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.8.1.3.3.4-4: 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.8.1.3.3.4-5: 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.8.2 Notifications

Notifications are not applicable to this API.

5.8.3 Data Model

5.8.3.1 General

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

Table 5.8.3.1-1 specifies the data types defined for the ApplyingBdtPolicy API.

Table 5.8.3.1-1: ApplyingBdtPolicy API specific Data Types

Data type	Clause defined	Description	Applicability
AppliedBdtPolicy	5.8.3.3.2	Represents an applied BDT policy.
AppliedBdtPolicyPatch	5.8.3.3.3	Represents the parameters to request the modification of a subscription to applied BDT policy.

5.8.3.2 Reused data types

The data types reused by the ApplyingBdtPolicy API from other specifications are listed in table 5.8.3.2-1.

Table 5.8.3.2-1: Re-used Data Types

Data type	Reference	Comments
BdtReferenceId	3GPP TS 29.122 [4]	Identifier of a selected BDT policy.
Gpsi	3GPP TS 29.571 [8]	Identifies a GPSI.
ExternalGroupId	3GPP TS 29.122 [4]	External Group Identifier for a user group.
SupportedFeatures	3GPP TS 29.571 [8]	Used to negotiate the applicability of the optional features defined in table 5.8.4-1.

5.8.3.3 Structured data types

5.8.3.3.1 Introduction

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

5.8.3.3.2 Type: AppliedBdtPolicy

This type represents an applied BDT policy which is sent from the AF to the NEF.

Table 5.8.3.3.2-1: Definition of type AppliedBdtPolicy

Attribute name	Data type	P	Cardinality	Description	Applicability (NOTE)
bdtRefId	BdtReferenceId	M	1	Identifies a selected policy of background data transfer.
gpsi	Gpsi	C	0..1	Identifies a user.
externalGroupId	ExternalGroupId	C	0..1	Identifies a user group.
suppFeat	SupportedFeatures	M	1	Indicates the list of Supported features used as described in clause 5.8.4. This attribute shall be provided in the POST request and in the response of successful resource creation
self	Link	C	0..1	Identifies the Individual Applied BDT Policy Subscription resource. Shall be present in the HTTP GET response when reading all the subscriptions for an AF.
NOTE: Only one of the properties "gpsi" or "externalGroupId" shall be included.

5.8.3.3.3 Type: AppliedBdtPolicyPatch

This type represents a subscription of applied BDT policy parameters provided by the AF to the NEF. The structure is used for HTTP PATCH request.

Table 5.8.3.3.2-1: Definition of type AppliedBdtPolicyPatch

Attribute name	Data type	P	Cardinality	Description	Applicability
bdtRefId	BdtReferenceId	M	1	Identifies a selected policy of background data transfer.

5.8.3.4 Simple data types and enumerations

5.8.3.4.1 Introduction

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

5.8.3.4.2 Simple data types

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

Table 5.8.3.4.2-1: Simple data types

Type Name	Type Definition	Description	Applicability

5.8.4 Used Features

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

Table 5.8.4-1: Features used by ApplyingBdtPolicy API

Feature number	Feature Name	Description

5.8.5 Error handling

5.8.5.1 General

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

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

5.8.5.2 Protocol Errors

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

5.8.5.3 Application Errors

The application errors defined for ApplyingBdtPolicy API are listed in table 5.8.5.3-1.

Table 5.8.5.3-1: Application errors

Application Error	HTTP status code	Description	Applicability