5.10 LpiParameterProvision API

29.5223GPP5G SystemNetwork Exposure Function Northbound APIsRelease 18Stage 3TS

5.10.1 Resources

5.10.1.1 Overview

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

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

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

Figure 5.10.1.1-1: Resource URI structure of the LpiParameterProvision API

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

Table 5.10.1.1-1: Resources and methods overview

Resource name	Resource URI	HTTP method	Description
LPI Parameters Provisionings	/{afId}/provisionedLpis (NOTE)	GET	Read all LPI Parameters Provisioning resources for a given AF
		POST	Create a new Individual LPI Parameters Provisioning resource
Individual LPI Parameters Provisioning	/{afId}/provisionedLpis/{provisionedLpiId} (NOTE)	GET	Read an existing Individual LPI Parameters Provisioning resource identified by {provisionedLpiId}
		PUT	Update all of the properties of an existing Individual LPI Parameters Provisioning resource identified by {provisionedLpiId}
		PATCH	Modify an existing Individual LPI Parameters Provisioning resource identified by {provisionedLpiId}.
		DELETE	Delete an existing Individual LPI Parameters Provisioning resource identified by {provisionedLpiId}
NOTE: The path segment "provisionedLpis" does not follow the related naming convention defined in clause 5.2. The path segment is however kept as currently defined in this specification for backward compatibility considerations.

5.10.1.2 Resource: LPI Parameters Provisionings

5.10.1.2.1 Introduction

This resource allows a AF to read all active LPI Parameters Provisionings for the given AF, or create an new individual LPI Parameters Provisioning resource to provision parameters to the NEF.

5.10.1.2.2 Resource Definition

Resource URI: {apiRoot}/3gpp-lpi-pp/v1/{afId}/provisionedLpis

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

Table 5.10.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.10.1.2.3 Resource Methods

5.10.1.2.3.1 General

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

5.10.1.2.3.2 GET

The GET method allows to read all active LPI Parameters Provisioning resources 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.10.1.2.3.2-1.

Table 5.10.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.10.1.2.3.2-2 and the response data structures and response codes specified in table 5.10.1.2.3.2-3.

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

Data type	P	Cardinality	Response codes	Description
array(LpiParametersProvision)	M	0..N	200 OK	All the LPI Parameters Provisioning information for the AF in the request URI are returned.
N/A			307 Temporary Redirect	Temporary redirection, during resource 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 resource 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.10.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.10.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.10.1.2.3.3 POST

The POST method creates a new resource to LPI Parameters Provisionings 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.10.1.2.3.3-1 and the response data structures and response codes specified in table 5.10.1.2.3.3-2.

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

Data type	P	Cardinality	Description
LpiParametersProvision	M	1	Parameters to create an Individual LPI Parameters Provisioning resource to provision parameters.

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

Data type	P	Cardinality	Response codes	Description
LpiParametersProvision	M	1	201 Created	The 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.10.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-lpi-pp/v1/{afId}/provisionedLpis/{provisionedLpiId}

5.10.1.3 Resource: Individual LPI Parameters Provisioning

5.10.1.3.1 Introduction

This resource allows a AF to read, update or delete an existing Individual LPI Parameters Provisioning resource.

5.10.1.3.2 Resource Definition

Resource URI: {apiRoot}/3gpp-lpi-pp/v1/{afId}/provisionedLpis/{provisionedLpiId}

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

Table 5.10.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.
provisionedLpiId	string	Identifier of the provisioning resource.

5.10.1.3.3 Resource Methods

5.10.1.3.3.1 General

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

5.10.1.3.3.2 GET

The GET method allows to read an active Individual LPI Parameters Provisioning resource for a given AF and provisionedLpiId. 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.10.1.3.3.2-1.

Table 5.10.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.10.1.3.3.2-2 and the response data structures and response codes specified in table 5.10.1.3.3.2-3.

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

Data type	P	Cardinality	Response codes	Description
LpiParametersProvision	M	1	200 OK	The information for the source in the request URI are returned.
N/A			307 Temporary Redirect	Temporary redirection, during resource 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 resource 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.10.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.10.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.10.1.3.3.3 PUT

The PUT method updates an existing resource to update an existing Individual LPI Parameters Provisioning resource. 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.10.1.3.3.3-1 and the response data structures and response codes specified in table 5.10.1.3.3.3-2.

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

Data type	P	Cardinality	Description
LpiParametersProvision	M	1	Update an existing individual LPI Parameters Provisioning resource to provision parameters.

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

Data type	P	Cardinality	Response codes	Description
LpiParametersProvision	M	1	200 OK	The resource was updated successfully and a representation of the updated resource is returned.
n/a			204 No Content	The resource was updated successfully and no additional content is sent in the response message.
n/a			307 Temporary Redirect	Temporary redirection, during resource 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 resource 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.10.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.10.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.10.1.3.3.3A PATCH

The PATCH method modifies an existing resource to update an existing individual LPI Parameters Provisioning resource. 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.10.1.3.3.3A-1 and the response data structures and response codes specified in table 5.10.1.3.3.3A-2.

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

Data type	P	Cardinality	Description
LpiParametersProvisionPatch	M	1	Modify an existing individual LPI Parameters Provisioning resource to provision parameters.

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

Data type	P	Cardinality	Response codes	Description
LpiParametersProvision	M	1	200 OK	The resource was updated successfully and a representation of the updated resource is returned.
n/a			204 No Content	The resource was updated successfully and no additional content is sent in the response message.
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.10.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.10.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.10.1.3.3.4 DELETE

The DELETE method deletes an existing individual LPI Parameters Provisioning resource 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.10.1.3.3.4-1.

Table 5.10.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.10.1.3.3.4-2 and the response data structures and response codes specified in table 5.10.1.3.3.4-3.

Table 5.10.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.10.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 resource was removed successfully.
N/A			307 Temporary Redirect	Temporary redirection, during resource 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 resource 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.10.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.10.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.10.2 Data Model

5.10.2.1 General

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

Table 5.10.2.1-1 specifies the data types defined for the LpiParameterProvision API.

Table 5.10.2.1-1: LpiParameterProvision API specific Data Types

Data type	Clause defined	Description	Applicability
LpiParametersProvision	5.10.2.3.2	Represents an individual LPI Parameters Provisioning resource.

5.10.2.2 Reused data types

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

Table 5.10.2.2-1: Re-used Data Types

Data type	Reference	Comments
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]	Identifies a referenced resource.
Lpi	3GPP TS 29.503 [17]	Identifies the Location Privacy Indication information.
MtcProviderInformation	3GPP TS 29.571 [8]	Indicates MTC provider information for LCS privacy parameter configuration authorization.
SupportedFeatures	3GPP TS 29.571 [8]	Used to negotiate the applicability of the optional features defined in table 5.10.3-1.

5.10.2.3 Structured data types

5.10.2.3.1 Introduction

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

5.10.2.3.2 Type: LpiParametersProvision

Table 5.10.2.3.2-1: Definition of type LpiParametersProvision

Attribute name	Data type	P	Cardinality	Description	Applicability
self	Link	C	0..1	Identifies the individual parameters provisioning resource. This attribute shall be supplied by the NEF in HTTP responses that include an object of LpiParametersProvision type.
exterGroupId	ExternalGroupId	O	0..1	Identifies a group of UEs. (NOTE 1)
gpsi	Gpsi	O	0..1	Identifies an UE with GPSI. (NOTE 1))
lpi	Lpi	M	1	Location Privacy Indication parameters
mtcProviderId	MtcProviderInformation	O	0..1	Indicates MTC provider information for LCS privacy parameter configuration authorization. (NOTE 2))
suppFeat	SupportedFeatures	M	1	Indicates the negotiated supported features.
NOTE 1: Only one of the "gpsi" or "exterGroupId" attribute shall be provided. NOTE 2: The NEF should check received MTC Provider information and then the NEF may: – override it with local configured value and send it to UDM; – send it directly to the UDM; or – reject the LPI Parameter Provisioning request.

5.10.2.3.3 Type: LpiParametersProvisionPatch

Table 5.10.2.3.3-1: Definition of type LpiParametersProvisionPatch

Attribute name	Data type	P	Cardinality	Description	Applicability
lpi	Lpi	O	1	Location Privacy Indication parameters
mtcProviderId	MtcProviderInformation	O	0..1	Indicates MTC provider information for LCS privacy parameter configuration authorization. (NOTE 1)
NOTE 1: The NEF should check received MTC Provider information and then the NEF may: – override it with local configured value and send it to UDM; – send it directly to the UDM; or – reject the LPI Parameter Provisioning modification request.

5.10.2.4 Simple data types and enumerations

5.10.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.10.2.4.2 Simple data types

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

Table 5.10.2.4.2-1: Simple data types

Type Name	Type Definition	Description	Applicability

5.10.3 Used Features

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

Table 5.10.3-1: Features used by LpiParameterProvision 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 resource).

5.10.4 Error handling

5.10.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.10.4.2 Protocol Errors

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

5.10.4.3 Application Errors

The application errors defined for LpiParameterProvision API are listed in table 5.10.4.3-1.

Table 5.10.4.3-1: Application errors

Application Error	HTTP status code	Description	Applicability