5.23 DataReporting API

29.5223GPP5G SystemNetwork Exposure Function Northbound APIsRelease 18Stage 3TS

Tools: ARFCN - Frequency Conversion for 5G NR/LTE/UMTS/GSM

5.23.1 Introduction

The Nnef_DataReporting service shall use the DataReporting API.

The API URI of DataReporting API shall be:

{apiRoot}/<apiName>/<apiVersion>

The request URIs used in HTTP requests shall have the Resource URI structure defined in clause 5.2.4 of 3GPP TS 29.122 [2], i.e.:

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

with the following components:

– "apiRoot" is set as defined in clause 5.2.4 of 3GPP TS 29.122 [4].

– "apiName" shall be set to "3gpp-data-reporting".

– "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 API URI.

5.23.2 Resources

This clause describes the structure for the Resource URIs as shown in Figure 5.23.2-1 and the resources and HTTP methods used for the DataReporting API.

Figure 5.23.2-1: Resource URI structure of the DataReporting API

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

Table 5.23.2-1: Resources and methods overview

Resource name	Resource URI (relative path under API URI)	HTTP method or custom operation	Description (service operation)
Data Reporting Sessions	/sessions	POST	Create a Data Reporting Session
Individual Data Reporting Session	/sessions/{sessionId}	GET	Retreive an existing Individual Data Reporting Session resource.
		PUT	Update an Individual existing Data Reporting Session resource.
		DELETE	Delete an existing Individual Data Reporting Session resource.
		report (POST)	Report data.

5.23.2.2 Resource: Data Reporting Sessions

5.23.2.2.1 Introduction

This resource represents the collection of Data Reporting Sessions managed by the NEF.

This resource is modelled with the Collection resource archetype (see clause C.2 of 3GPP TS 29.501 [3]).

5.23.2.2.2 Resource definition

Resource URL: {apiRoot}/3gpp-data-reporting/v1/sessions

This resource shall support the resource URL variables defined in table 5.23.2.2.2-1.

Table 5.23.2.2.2-1: Resource URL variables for this resource

Name	Data type	Definition
apiRoot	string	See clause 5.213.1.

5.23.2.2.3 Resource Methods

5.23.2.2.3.1 POST

This method enables an AF to request the creation of a Data Reporting Session at the NEF.

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

Table 5.23.2.2.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 5.23.2.2.3.1-2 and the response data structures and response codes specified in table 5.23.2.2.3.1-4.

Table 5.23.2.2.3.1-2: Data structures supported by the POST request body on this resource

Data type	P	Cardinality	Description
DataReportingSession (NOTE)	M	1	Representation of the Data Reporting Session to be created in the NEF.
NOTE: The "sessionId" attribute of the DataReportingSession data type shall not be provided as it is not applicable.

Table 5.23.2.2.3.1-3: Data structures supported by the POST response body on this resource

Data type

Cardinality

Response

codes

Description

DataReportingSession

(NOTE 2)

201 Created

Successful case. A representation of the created Individual Data Reporting Session resource is returned.

The URI of the created resource shall be returned in an HTTP "Location" header.

NOTE 1: 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.

NOTE 2: The “sessionId” attribute of the DataReportingSession data type shall not be provided as it is not applicable.

Table 5.23.2.2.3.1-4: Headers supported by the 201 response code on this resource

HTTP response header	Data type	P	Cardinality	Description
Location	string	M	1	The URI of the newly created resource, according to the structure: {apiRoot}/3gpp-data-reporting/v1/sessions/{sessionId}

5.23.2.3 Resource: Individual Data Reporting Session

5.23.2.3.1 Introduction

This resource represents an Individual Data Reporting Session managed bythe NEF.

This resource is modelled with the Document resource archetype (see clause C.1 of 3GPP TS 29.501 [3]).

5.23.2.3.2 Resource Definition

Resource URL: {apiRoot}/3gpp-data-reporting/v1/sessions/{sessionId}

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

Table 5.23.2.3.2-1: Resource URL variables for this resource

Name	Data type	Definition
apiRoot	string	See clause 5.23.1
sessionId	string	Represents the identifier of the Individual Data Reporting Sessions resource.

5.23.2.3.3 Resource standard methods

5.23.2.3.3.1 GET

This method enables an AF to retrieve an existing Individual Data Reporting Session resource at the NEF.

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

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

Name	Data type	P	Cardinality	Description	Applicability
n/a

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

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

Data type	P	Cardinality	Description
n/a

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

Data type	P	Cardinality	Response codes	Description
DataReportingSession	M	1	200 OK	Successful case. The requested Individual Data Reporting Session resource is returned to the AF.
n/a			307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing an alternative target URI 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 target URI located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
NOTE 1: The mandatory HTTP error status code for the GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. NOTE 2: The “sessionId” attribute of the DataReportingSession data type shall not be provided as it is not applicable.

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

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative target URI located in an alternative NEF.

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

Name	Data type	P	Cardinality	Description
Location	string	M	1	An alternative target URI of the resource located in an alternative NEF.

5.23.2.3.3.2 PUT

This method enables an AF to update an existing Individual Data Reporting Session resource at the NEF.

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

Table 5.23.2.3.3.2-1: URI query parameters supported by the PUT method on this resource

Name	Data type	P	Cardinality	Description

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

Table 5.23.2.3.3.2-2: Data structures supported by the PUT request body on this resource

Data type	P	Cardinality	Description
DataReportingSession	M	1	Parameters to update the Individual Data Reporting Session resource.
NOTE: The “sessionId” attribute of the DataReportingSession data type shall not be provided as it is not applicable.

Table 5.23.2.3.3.2-3: Data structures supported by the PUT response body on this resource

Data type	P	Cardinality	Response codes	Description
DataReportingSession	M	1	200 OK	The Individual Data Reporting Session resource was updated successfully and a representation of the created resource is returned in the response body.
n/a			204 No Content	The Individual Data Reporting Session resource was successfully updated and no content is to be returned in the response body.
n/a			307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing an alternative target URI 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 target URI located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
NOTE 1: The mandatory HTTP error status code for the PUT method listed in Table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. NOTE 2: The "sessionId" attribute of the DataReportingSession data type shall not be provided as it is not applicable.

Table 5.23.2.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.23.2.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.23.2.3.3.3 DELETE

This method enables an AF to request the deletion of an Individual Data Reporting Session resource at the NEF.

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

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

Table 5.23.2.3.3.3-2: Data structures supported by the DELETE request body on this resource

Data type	P	Cardinality	Description
n/a

Table 5.23.2.3.3.3-3: Data structures supported by the DELETE response body on this resource

Data type	P	Cardinality	Response Codes	Description
n/a			204 No Content	Successful response. The Individual Data Reporting Session resource was successfully deleted.
			307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing an alternative target URI located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
			308 Permanent Redirect	Permanent redirection. The response shall include a Location header field containing an alternative target URI located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4].
NOTE 1: The mandatory HTTP error status code for the DELETE method listed in Table 5.2.6-1 of 3GPP TS 29.122 [4] also apply.

Table 5.23.2.3.3.3-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.23.2.3.3.3-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.23.2.3.4 Resource custom operations

5.23.2.3.4.1 Overview

Table 5.23.2.3.4.1-1: Custom operations

Operation name	Custom operaration URI	Mapped HTTP method	Description
Report	/sessions/{sessionId}/report	POST	Enables to send collected UE data reports.

5.23.2.3.4.2 Operation: Report

5.23.2.3.4.2.1 Description

The custom operation enables an AF to send collected UE data reports to the NEF.

5.23.2.3.4.2.2 Operation Definition

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

Table 5.23.2.3.4.2.2-1: Data structures supported by the POST request body on this resource

Data type	P	Cardinality	Description
DataReport	M	1	UE data reported by the data collection client.

Table 5.23.2.3.4.2.2-2: Data structures supported by the POST response body on this resource

Data type	P	Cardinality	Response codes	Description
DataReportingSession	O	0..1	200 OK	The UE data report was successfully received.
n/a			307 Temporary Redirect	Temporary redirection. The response shall include a Location header field containing an alternative target URI 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 target URI located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]
NOTE 1: The mandatory HTTP error status code for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. NOTE 2: The “sessionId” attribute of the DataReportingSession data type shall not be provided as it is not applicable.

Table 5.23.2.3.4.2.2-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.23.2.3.4.2.2-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.23.3 Custom Operations without associated resources

There are no custom operations without associated resources defined for this API in this release of the specification.

5.23.4 Notifications

There are no notifications defined for this API in this release of the specification.

5.23.5 Data Model

5.23.3.1 General

This clause specifies the application data model supported by the DataReporting API. Table 5.23.5.1-1 specifies the data types defined for the DataReporting API.

Table 5.23.5.1-1: DataReporting specific Data Types

Data type	Clause defined	Description
n/a

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

Table 5.23.5.1-2: Re-used Data Types

Data type	Reference	Comments	Applicability
DataReport	3GPP TS 26.532 [60]	Reported data by the AF.
DataReportingSession	3GPP TS 26.532 [60]	Configuration by the AF specifying the data to be reported.

5.23.6 Used Features

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

Table 5.23.6-1: Features used by DataReporting API

Feature number	Feature Name	Description

5.23.7 Error handling

5.23.7.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.23.7.2 Protocol Errors

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

5.23.7.3 Application Errors

The application errors defined for the DataReporting API are listed in table 5.23.7.3-1.

Table 5.23.7.3-1: Application errors

Application Error	HTTP status code	Description