5.12 ACSParameterProvision API

29.5223GPP5G SystemNetwork Exposure Function Northbound APIsRelease 18Stage 3TS

5.12.1 Resources

5.12.1.1 Overview

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

{apiRoot}/3gpp-acs-pp/v1

"apiRoot" is set as described in clause 5.2.4 in 3GPP TS 29.122 [4]. "apiName" shall be set to "3gpp-acs-pp" 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.12.1.1-1 and the resources and HTTP methods used for the ACSParameterProvision API.

Figure 5.12.1.1-1: Resource URI structure of the ACSParameterProvision API

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

Table 5.12.1.1-1: Resources and methods overview

Resource name	Resource URI	HTTP method	Description
ACS Configuration Subscripions	/{afId}/subscriptions	GET	Read all subscriptions for a given AF.
		POST	Create a new ACS configuration subscription.
Individual ACS Configuration Subscripion	/{afId}/subscriptions/{subscriptionId}	GET	Read an existing subscription identified by {subscriptionId}
		PUT	Update all of the properties of an existing subscription identified by {subscriptionId}.
		PATCH	Modify an existing subscription identified by {subscriptionId}.
		DELETE	Delete a subscription identified by {subscriptionId}

5.12.1.2 Resource: ACS Configuration Subscriptions

5.12.1.2.1 Introduction

This resource allows a AF to read all active ACS Configuration Subscriptions for the given AF, or create an new individual ACS Configuration subscription in the NEF.

5.12.1.2.2 Resource Definition

Resource URI: {apiRoot}/3gpp-acs-pp/v1/{afId}/subscriptions

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

Table 5.12.1.2.2-1: Resource URI variables for this resource

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

5.12.1.2.3 Resource Methods

5.12.1.2.3.1 General

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

5.12.1.2.3.2 GET

The GET method allows to read all active 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.12.1.2.3.2-1.

Table 5.12.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.12.1.2.3.2-2 and the response data structures and response codes specified in table 5.12.1.2.3.2-3.

Table 5.12.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.12.1.2.3.2-3: Data structures supported by the GET Response Body on this resource

Data type	P	Cardinality	Response codes	Description
array(AcsConfigurationData)	M	0..N	200 OK	All 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.12.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.12.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.12.1.2.3.3 POST

The POST method creates a new resource to individual ACS Configuration 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.12.1.2.3.3-1 and the response data structures and response codes specified in table 5.12.1.2.3.3-2.

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

Data type	P	Cardinality	Description
AcsConfigurationData	M	1	Parameters to create an individual ACS Configuration subscription resource.

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

Data type	P	Cardinality	Response codes	Description
AcsConfigurationData	M	1	201 Created	The subscription resource 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.12.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-acs-pp/v1/{afId}/subscriptions/{subscriptionId}

5.12.1.3 Resource: Individual ACS Configuration Subscription

5.12.1.3.1 Introduction

This resource allows a AF to read, update or delete an existing ACS Configuration subscription.

5.12.1.3.2 Resource Definition

Resource URI: {apiRoot}/3gpp-acs-pp/v1/{afId}/subscriptions/{subscriptionId}

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

Table 5.12.1.3.2-1: Resource URI variables for this resource

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

5.12.1.3.3 Resource Methods

5.12.1.3.3.1 General

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

5.12.1.3.3.2 GET

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

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

Table 5.12.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.12.1.3.3.2-2 and the response data structures and response codes specified in table 5.12.1.3.3.2-3.

Table 5.12.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.12.1.3.3.2-3: Data structures supported by the GET Response Body on this resource

Data type	P	Cardinality	Response codes	Description
AcsConfigurationData	M	1	200 OK	The information for the subscription 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.12.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.12.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.12.1.3.3.3 PUT

The PUT method updates an existing resource to update a configuration. The AF shall initiate the HTTP PUT request message and the NEF shall respond to the message.

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

Table 5.12.1.3.3.3-1: Data structures supported by the PUT Request Body on this resource

Data type	P	Cardinality	Description
AcsConfigurationData	M	1	Modify an existing subscription.

Table 5.12.1.3.3.3-2: Data structures supported by the PUT Response Body on this resource

Data type	P	Cardinality	Response codes	Description
AcsConfigurationData	M	1	200 OK	The subscription resource was updated successfully and a representation of the updated resource is returned.
n/a			204 No Content	The subscription resource was updated 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 PUT method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.12.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.12.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.12.1.3.3.3A PATCH

The PATCH method modifies an existing resource to update an existing ACS Configuration Subscripion. 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.9.1.3.3.3A-1 and the response data structures and response codes specified in table 5.9.1.3.3.3A-2.

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

Data type	P	Cardinality	Description
AcsConfigurationDataPatch	M	1	Modify an existing subscription.

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

Data type	P	Cardinality	Response codes	Description
AcsConfigurationData	M	1	200 OK	The subscription resource was modified successfully and a representation of the updated resource is returned.
n/a			204 No Content	The subscription resource was modified successfully.
n/a			307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
n/a			308 Permanent Redirect	Permanent redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
NOTE: The mandatory HTTP error status codes for the PATCH method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.12.1.3.3.3A-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.12.1.3.3.3A-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.12.1.3.3.4 DELETE

The DELETE method deletes an existing individual 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.12.1.3.3.4-1.

Table 5.12.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.12.1.3.3.4-2 and the response data structures and response codes specified in table 5.12.1.3.3.4-3.

Table 5.12.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.12.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 resource 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.12.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.12.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.12.2 Data Model

5.12.2.1 General

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

Table 5.12.2.1-1 specifies the data types defined for the ACSParameterProvision API.

Table 5.12.2.1-1: ACSParameterProvision API specific Data Types

Data type	Clause defined	Description	Applicability
AcsConfigurationData	5.12.2.3.2	Represents an individual ACS Configuration subscription resource.
AcsConfigurationDataPatch	5.12.2.3.3	Represents the parameters to request to modify an existing ACS Configuration subscription.	PatchUpdate

5.12.2.2 Reused data types

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

Table 5.12.2.2-1: Re-used Data Types

Data type	Reference	Comments
AcsInfo	3GPP TS 29.571 [8]	Contains the information of ACS
ExternalGroupId	3GPP TS 29.122 [4]	External Group Identifier for a user group.
Gpsi	3GPP TS 29.571 [8]	Identifies a GPSI.
Link	3GPP TS 29.122 [4]
MtcProviderInformation	3GPP TS 29.571 [8]	Indicates MTC provider information.
SupportedFeatures	3GPP TS 29.571 [8]	Used to negotiate the applicability of the optional features defined in table 5.9.4-1.

5.12.2.3 Structured data types

5.12.2.3.1 Introduction

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

5.12.2.3.2 Type: AcsConfigurationData

Table 5.12.2.3.2-1: Definition of type AcsConfigurationData

Attribute name	Data type	P	Cardinality	Description	Applicability
self	Link	C	0..1	Identifies the individual service parameter subscription resource URI. Shall be present by the NEF in HTTP responses that include an object of AcsConfigurationData Data type.
gpsi	Gpsi	O	0..1	Identifies GPSI. (NOTE)
exterGroupId	ExternalGroupId	O	0..1	Represents a group of users. (NOTE)
acsInfo	AcsInfo	M	1	Contains the information of ACS.
mtcProviderId	MtcProviderInformation	O	0..1	Indicates MTC provider information.
suppFeat	SupportedFeatures	M	1	Indicates the list of Supported features used as described in clause 5.12.3. This parameter shall be supplied by the NF service consumer in the POST request that requested the creation of an individual ACS configuration Subscription resource.
NOTE: Only one of the "gpsi" or "exterGroupId" attribute shall be provided.

5.12.2.3.3 Type: AcsConfigurationDataPatch

Table 5.12.2.3.3-1: Definition of type AcsConfigurationDataPatch

Attribute name	Data type	P	Cardinality	Description	Applicability
acsInfo	AcsInfo	O	0..1	Contains the information of ACS.
mtcProviderId	MtcProviderInformation	O	0..1	Indicates MTC provider information.

5.12.2.4 Simple data types and enumerations

5.12.2.4.1 Introduction

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

5.12.2.4.2 Simple data types

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

Table 5.12.2.4.2-1: Simple data types

Type Name	Type Definition	Description	Applicability

5.12.3 Used Features

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

Table 5.12.3-1: Features used by ACSParameterProvision API

Feature number	Feature Name	Description
1	PatchUpdate	Indicates the support of enhancements to the northbound interfaces (e.g. support the partial modification of an existing subscription resource).

5.12.4 Error handling

5.12.4.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.12.4.2 Protocol Errors

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

5.12.4.3 Application Errors

The application errors defined for ACSParameterProvision API are listed in table 5.12.4.3-1.

Table 5.12.4.3-1: Application errors

Application Error	HTTP status code	Description	Applicability