5.9 ReportingNetworkStatus API

29.1223GPPRelease 18T8 reference point for Northbound APIsTS

5.9.1 Overview

The ReportingNetworkStatus API is a RESTful API that allows the SCS/AS to be one-time or continuous notified of the network status in a geographic area. The ReportingNetworkStatus API defines a set of data models, resources and the related procedures for the creation and management of the network status reporting request. The corresponding JSON schema for the representation of the resources and operations defined by the ReportingNetworkStatus API is provided in its complete form in Annex A.9.

5.9.2 Data model

5.9.2.1 Resource data types

5.9.2.1.1 Introduction

This clause defines data structures to be used in resource representations.

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

Table 5.9.2.1.1-1: ReportingNetworkStatus API re-used Data Types

Data type

Reference

Comments

GeographicArea

3GPP TS 29.572 [42]

Identifies the geographical information of the user(s).

CivicAddress

3GPP TS 29.572 [42]

Identifies the civic address information of the user(s).

SupportedFeatures

3GPP TS 29.571 [45]

Used to negotiate the applicability of the optional features defined in table 5.9.4-1.

Table 5.9.2.1.1-2 specifies the data types defined for the ReportingNetworkStatus API.

Table 5.9.2.1.1-2: ReportingNetworkStatus API specific Data Types

Data type

Clause defined

Description

Applicability

CongestionType

5.9.2.3.3

Represents abstracted values for congestion status.

CongestionValue

5.9.2.3.2

Represents the congestion level value

NetStatusRepSubsPatch

5.9.2.1.3

Represents the parameters to request the modification of network status reporting subscription.

PatchUpdate

NetworkStatusReportingNotification

5.9.2.2.2

Represents a network status reporting notification.

NetworkStatusReportingSubscription

5.9.2.1.2

Represents a subscription to network status information reporting.

5.9.2.1.2 Type: NetworkStatusReportingSubscription

This type represents the subscription of reporting the network status. The same structure is used in the subscription request and subscription response.

Table 5.9.2.1.2-1: Definition of type NetworkStatusReportingSubscription

Attribute name

Data type

Cardinality

Description

Applicability (NOTE 1)

self

Link

0..1

Link to the resource "Individual Network Status

Reporting subscription". This parameter shall be supplied by the SCEF in HTTP responses.

supportedFeatures

SupportedFeatures

0..1

Used to negotiate the supported optional features of the API as described in clause 5.2.7.

This attribute shall be provided in the POST request and in the response of successful resource creation.

notificationDestination

Link

1

A URI indicating the notification destination where T8 notification requests shall be delivered

requestTestNotification

boolean

0..1

Set to true by the SCS/AS to request the SCEF to send a test notification as defined in clause 5.2.5.3. Set to false or omitted otherwise.

Notification_test_event

websockNotifConfig

WebsockNotifConfig

0..1

Configuration parameters to set up notification delivery over Websocket protocol as defined in clause 5.2.5.4.

Notification_websocket

locationArea

LocationArea

1

Identifies a location area. It can be either a list of cell IDs, or a list of Tracking Areas, or civic addresses, or a geographic area, or a combination of any of the above.

timeDuration

DateTime

0..1

Identifies the time for which a continuous reporting is requested. Shall not be provided for one time reporting case.

thresholdValues

array(CongestionValue)

0..N

Identifies a list of congestion level(s) with exact value that the SCS/AS requests to be informed of when reached.

(NOTE 2)

thresholdTypes

array(CongestionType)

0..N

Identifies a list of congestion level(s) with abstracted value that the SCS/AS requests to be informed of when reached.

(NOTE 2)

NOTE 1: Properties marked with a feature as defined in clause 5.9.4 are applicable as described in clause 5.2.7. If no feature are indicated, the related property applies for all the features.

NOTE 2: thresholdValues and thresholdTypes shall be mutually exclusive.

5.9.2.1.3 Type: NetStatusRepSubsPatch

This data type represents the parameters to request the modification of network status reporting subscription.

Table 5.9.2.1.3-1: Definition of type NetStatusRepSubsPatch

Attribute name

Data type

Cardinality

Description

Applicability (NOTE 1)

notificationDestination

Link

0..1

A URI indicating the notification destination where T8 notification requests shall be delivered.

locationArea

LocationArea

0..1

Identifies a location area. It can be either a list of cell IDs, or a list of Tracking Areas, or civic addresses, or a geographic area, or a combination of any of the above.

timeDuration

DateTimeRm

0..1

Identifies the time for which a continuous reporting is requested. Shall not be provided for one time reporting case.

thresholdValues

array(CongestionValue)

0..N

Identifies a list of congestion level(s) with exact value that the SCS/AS requests to be informed of when reached.

(NOTE 2)

thresholdTypes

array(CongestionType)

0..N

Identifies a list of congestion level(s) with abstracted value that the SCS/AS requests to be informed of when reached.

(NOTE 2)

NOTE 1: Properties marked with a feature as defined in clause 5.9.4 are applicable as described in clause 5.2.7. If no feature are indicated, the related property applies for all the features.

NOTE 2: The "thresholdValue" attribute and the "thresholdType" attribute shall be mutually exclusive.

5.9.2.2 Notification data types

5.9.2.2.1 Introduction

This clause defines data structures to be used in notifications.

5.9.2.2.2 Type: NetworkStatusReportingNotification

This data type represents a network status reporting notification which is sent from the SCEF to the SCS/AS.

Table 5.9.2.2.2-1: Definition of type NetworkStatusReportingNotification

Attribute name

Data type

Cardinality

Description

Applicability (NOTE 1)

subscription

Link

1

Link to the subscription resource to which this notification is related.

nsiValue

CongestionValue

0..1

Network Status Indicator based on exact value for congestion status received from RCAF(s).

(NOTE 2)

nsiType

CongestionType

0..1

Network Status Indicator based on abstracted value for congestion status.

(NOTE 2)

NOTE 1: Properties marked with a feature as defined in clause 5.9.4 are applicable as described in clause 5.2.7. If no features are indicated, the related property applies for all the features.

NOTE 2: nsiValue and nsiType shall be mutually exclusive.

5.9.2.3 Referenced simple data types and enumerations

5.9.2.3.1 Introduction

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

5.9.2.3.2 Simple data types

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

Table 5.9.2.3.2-1: Simple data types

Type name

Description

CongestionValue

Unsigned integer with valid values between 0 and 31. The value 0 indicates that there is no congestion. The value 1 is the lowest congestion level and value 31 is the highest congestion level.

5.9.2.3.3 Enumeration: CongestionType

The enumeration CongestionType represents abstracted values for congestion status.

Table 5.9.2.3.3-1: Enumeration CongestionType

Enumeration value

Description

Applicability (NOTE)

HIGH

The congestion status is high.

MEDIUM

The congestion status is medium.

LOW

The congestion status is low.

NOTE: Properties marked with a feature as defined in clause 5.9.4 are applicable as described in clause 5.2.7. If no features are indicated, the related property applies for all the features.

5.9.3 Resource structure

5.9.3.1 General

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

{apiRoot}/3gpp-net-stat-report/v1

"apiRoot" is set as described in clause 5.2.4. All resource URIs in the clauses below are defined relative to the above root URI.

The following resources and HTTP methods are supported for this API:

Table 5.9.3.1-1: Resources and methods overview

Resource name

Resource URI

HTTP method

Meaning

Network Status

Reporting Subscriptions

/{scsAsId}/subscriptions

GET

Read all network status reporting subscription resources for a given SCS/AS.

POST

Create a new network status reporting subscription resource.

Individual Network Status

Reporting subscription

/{scsAsId}/subscriptions/{subscriptionId}

GET

Read a network status reporting subscription resource.

PUT

Update an existing Individual Network Status Reporting Subscription resource.

PATCH

Modify an existing Individual Network Status Reporting Subscription resource.

DELETE

Delete an existing continuous network status reporting subscription resource.

5.9.3.2 Resource: Network Status Reporting Subscriptions

5.9.3.2.1 Introduction

This resource allows the SCS/AS to read all active long-term subscriptions related to a network status reporting.

5.9.3.2.2 Resource definition

Resource URI: {apiRoot}/3gpp-net-stat-report/v1/{scsAsId}/subscriptions

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

Table 5.9.3.2.2-1: Resource URI variables for resource "Network Status Reporting Subscriptions"

Name

Data type

Definition

apiRoot

string

See clause 5.2.4.

scsAsId

string

Identifier of the SCS/AS.

5.9.3.2.3 Resource methods
5.9.3.2.3.1 GET

The GET method allows to read all active network status reporting subscriptions for a given SCS/AS. The SCS/AS shall initiate the HTTP GET request message and the SCEF shall respond to the message.

This method shall support the URI query parameters, request and response data structures, and response codes, as specified in the table 5.9.3.2.3.1-1 and table 5.9.3.2.3.1-2.

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

Name

Data type

Cardinality

Remarks

none specified

Table 5.9.3.2.3.1-2: Data structures supported by the GET request/response by the resource

Request body

Data type

Cardinality

Remarks

none

Response body

Data type

Cardinality

Response

codes

Remarks

array(NetworkStatusReportingSubscription)

0..N

200 OK

The information about the network status reporting subscriptions related to the request URI is returned.

none

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

Redirection handling is described in clause 5.2.10.

none

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

Redirection handling is described in clause 5.2.10.

NOTE: The mandatory HTTP error status codes for the GET method listed in table 5.2.6-1 also apply.

Table 5.9.3.2.3.1-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 SCEF.

Table 5.9.3.2.3.1-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 SCEF.

5.9.3.2.3.2 PUT

This HTTP method is not supported for the resource.

5.9.3.2.3.3 PATCH

This HTTP method is not supported for the resource.

5.9.3.2.3.4 POST

The POST method creates a new network status reporting subscription resource for a given SCS/AS. The SCS/AS shall initiate the HTTP POST request message and the SCEF shall respond to the message.

This method shall support the URI query parameters, request and response data structures, and response codes, as specified in the table 5.9.3.2.3.4-1 and table 5.9.3.2.3.4-2.

Table 5.9.3.2.3.4-1: URI query parameters supported by the POST method on this resource

Name

Data type

Cardinality

Remarks

none specified

Table 5.9.3.2.3.4-2: Data structures supported by the POST request/response by the resource

Request body

Data type

Cardinality

Remarks

NetworkStatusReportingSubscription

1

Parameters to register a subscription to request notifications about network status information report with the SCEF.

Response body

Data type

Cardinality

Response

codes

Remarks

NetworkStatusReportingSubscription

1

201 Created

The subscription was created successfully.

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

ProblemDetails

0..1

403 Forbidden

(NOTE 2)

NOTE 1: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 also apply.

NOTE 2: Failure cases are described in clause 5.9.5.3.

Table 5.9.3.2.3.4-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-net-stat-report/v1/{scsAsId}/subscriptions/{subscriptionId}

5.9.3.2.3.5 DELETE

This HTTP method is not supported for the resource.

5.9.3.3 Resource: Individual Network Status Reporting Subscription

5.9.3.3.1 Introduction

This resource allows the SCS/AS to request for being notified about the network status using a long-term subscription.

5.9.3.3.2 Resource definition

Resource URI: {apiRoot}/3gpp-net-stat-report/v1/{scsAsId}/subscriptions/{subscriptionId}

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

Table 5.9.3.3.2-1: Resource URI variables for resource "Individual Network Status Reporting Subscription"

Name

Data type

Definition

apiRoot

string

See clause 5.2.4.

scsAsId

string

Identifier of the SCS/AS.

subscriptionId

string

Identifier of the subscription resource. The subscriptionId corresponds to the stage 2 TLTRI.

5.9.3.3.3 Resource methods
5.9.3.3.3.1 GET

The GET method allows to read an active network status reporting subscription resource. The SCS/AS shall initiate the HTTP GET request message and the SCEF shall respond to the message.

This method shall support the URI query parameters, request and response data structures, and response codes, as specified in the table 5.9.3.3.3.1-1 and table 5.9.3.3.3.1-2.

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

Name

Data type

Cardinality

Remarks

none specified

Table 5.9.3.3.3.1-2: Data structures supported by the GET request/response by the resource

Request body

Data type

Cardinality

Remarks

none

Response body

Data type

Cardinality

Response

codes

Remarks

NetworkStatusReportingSubscription

1

200 OK

The subscription information related to the request URI is returned.

none

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

Redirection handling is described in clause 5.2.10.

none

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

Redirection handling is described in clause 5.2.10.

NOTE: The mandatory HTTP error status codes for the GET method listed in table 5.2.6-1 also apply.

Table 5.9.3.3.3.1-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 SCEF.

Table 5.9.3.3.3.1-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 SCEF.

5.9.3.3.3.2 PUT

The PUT method updates an existing subscription resource to update a subscription. The SCS/AS shall initiate the HTTP PUT request message and the SCEF shall respond to the message.

This method shall support the URI query parameters, request and response data structures, and response codes, as specified in the table 5.9.3.3.3.2-1 and table 5.9.3.3.3.2-2.

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

Name

Data type

Cardinality

Remarks

none specified

Table 5.9.3.3.3.2-2: Data structures supported by the PUT request/response by the resource

Request body

Data type

Cardinality

Remarks

NetworkStatusReportingSubscription

1

Parameters to update a subscription to request notifications about network status information report with the SCEF.

Response body

Data type

Cardinality

Response

codes

Remarks

NetworkStatusReportingSubscription

1

200 OK

The subscription was updated successfully.

none

204 No Content

The subscription was updated successfully.

none

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

Redirection handling is described in clause 5.2.10.

none

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

Redirection handling is described in clause 5.2.10.

NOTE: The mandatory HTTP error status codes for the PUT method listed in table 5.2.6-1 also apply.

Table 5.9.3.3.3.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 SCEF.

Table 5.9.3.3.3.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 SCEF.

5.9.3.3.3.3 PATCH

The PATCH method modifies an existing subscription resource to modify a subscription. The SCS/AS shall initiate the HTTP PATCH request message and the SCEF shall respond to the message.

This method shall support the URI query parameters, request and response data structures and response codes specified in the table 5.9.3.3.3.3-1 and table 5.9.3.3.3.3-2.

Table 5.9.3.3.3.3-1: URI query parameters supported by the PATCH method on this resource

Name

Data type

Cardinality

Remarks

n/a

Table 5.9.3.3.3.3-2: Data structures supported by the PATCH request/response by the resource

Request body

Data type

Cardinality

Remarks

NetStatusRepSubsPatch

1

Contains the parameters to modify an existing Individual Network Status Reporting Subscription resource.

Response body

Data type

Cardinality

Response

codes

Remarks

NetworkStatusReportingSubscription

1

200 OK

The modification of the Individual Network Status Reporting Subscription resource was successfull.

The SCEF shall return an updated representation of the resource within the NetworkStatusReportingSubscription data structure in the response message body.

n/a

204 No Content

The modification of the Individual Network Status Reporting Subscription resource was successfull and no content is to be sent in the response message body.

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

Redirection handling is described in clause 5.2.10.

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

Redirection handling is described in clause 5.2.10.

NOTE 1: The mandatory HTTP error status codes for the HTTP PATCH method listed in table 5.2.6-1 also apply.

Table 5.9.3.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 SCEF.

Table 5.9.3.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 SCEF.

5.9.3.3.3.4 POST

This HTTP method is not supported for the resource.

5.9.3.3.3.5 DELETE

The DELETE method deletes the resource and terminates the related network status reporting subscription. The SCS/AS shall initiate the HTTP DELETE request message and the SCEF shall respond to the message.

This method shall support the URI query parameters, request and response data structures, and response codes, as specified in the table 5.9.3.3.3.5-1 and table 5.9.3.3.3.5-2.

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

Name

Data type

Cardinality

Remarks

none specified

Table 5.9.3.3.3.5-2: Data structures supported by the DELETE request/response by the resource

Request body

Data type

Cardinality

Remarks

none

Response body

Data type

Cardinality

Response

codes

Remarks

none

204 No Content

The subscription was terminated successfully.

none

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

Redirection handling is described in clause 5.2.10.

none

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

Redirection handling is described in clause 5.2.10.

NOTE: The mandatory HTTP error status codes for the DELETE method listed in table 5.2.6-1 also apply.

Table 5.9.3.3.3.5-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 SCEF.

Table 5.9.3.3.3.5-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 SCEF.

5.9.3.4 Void

5.9.3A Notifications

5.9.3A.1 General

The notifications provided by the ReportingNetworkStatus API are specified in this clause.

Table 5.9.3A-1: Notifications overview

Notification

Callback URI

HTTP method or custom operation

Description

(service operation)

Network Status Reporting Notification

{notificationDestination}

POST

Report a detected network status for a subscription from the SCEF to the SCS/AS

5.9.3A.2 Network Status Reporting Notification

5.9.3A.2.1 Description

The Network Status Reporting Notification allows the SCEF to send notifications about the detected network status to the SCS/AS.

5.9.3A.2.2 Target URI

The Callback URI "{notification_uri}" shall be used with the callback URI variables defined in table 5.9.3A.2.2-1.

Table 5.9.3A.2.2-1: Callback URI variables

Name

Data type

Definition

notificationDestination

Link

Callback reference provided by the SCS/AS during creation or modification of the network status reporting subscription.

5.9.3A.2.3 Standard Methods
5.9.3A.2.3.1 Notification via POST

The HTTP POST method reports the detected network status for a network status subscription. The SCEF shall initiate the HTTP POST request message and the SCS/AS shall respond to the message.

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

Table 5.9.3A.2.3.1-1: Data structures supported by the POST Request Body

Data type

Cardinality

Description

NetworkStatusReportingNotification

1

The network status reporting notification provided by the SCEF.

Table 5.9.3A.2.3.1-2: Data structures supported by the POST Response Body

Data type

Cardinality

Response codes

Description

none

204 No Content

The network status reporting notification is received successfully.

none

307 Temporary Redirect

Temporary redirection, during notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative SCS/AS where the notification should be sent.

Redirection handling is described in clause 5.2.10.

none

308 Permanent Redirect

Permanent redirection, during notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative SCS/AS where the notification should be sent.

Redirection handling is described in clause 5.2.10.

NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 also apply.

Table 5.9.3A.2.3.1-3: Headers supported by the 307 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

An alternative URI representing the end point of an alternative SCS/AS towards which the notification should be redirected.

Table 5.9.3A.2.3.1-4: Headers supported by the 308 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

An alternative URI representing the end point of an alternative SCS/AS towards which the notification should be redirected.

5.9.3A.2.3.2 Notification via Websocket

If supported by both SCS/AS and SCEF and successfully negotiated, the NetworkStatusReportingNotification may alternatively be delivered through the Websocket mechanism as defined in clause 5.2.5.4.

5.9.4 Used Features

The table below defines the features applicable to the ReportingNetworkStatus API. Those features are negotiated as described in clause 5.2.7.

Table 5.9.4-1: Features used by ReportingNetworkStatus API

Feature Number

Feature

Description

1

Notification_websocket

The delivery of notifications over Websocket is supported according to clause 5.2.5.4. This feature requires that the Notification_test_event featute is also supported.

2

Notification_test_event

The testing of notifications connections is supported according to clause 5.2.5.3.

3

PatchUpdate

Indicates the support of enhancements to the northbound interfaces (e.g. support the partial modification of an existing subscription resource).

Feature: A short name that can be used to refer to the bit and to the feature, e.g. "Notification".

Description: A clear textual description of the feature.

5.9.5 Error handling

5.9.5.1 General

HTTP error handling shall be supported as specified in clause 5.2.6.

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

5.9.5.2 Protocol Errors

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

5.9.5.3 Application Errors

The application errors defined for the ReportingNetworkStatus API are listed in table 5.9.5.3-1.

Table 5.9.5.3-1: Application errors

Application Error

HTTP status code

Description

QUOTA_EXCEEDED

403 Forbidden

Not enough quota for SCS/AS.