5.12 ECRControl API
29.1223GPPRelease 18T8 reference point for Northbound APIsTS
5.12.1 Overview
The ECRControl API is a custom API (RPC interaction) that allows the SCS/AS to query or configure the enhanced converage restriction over 3GPP networks. The ECRControl API defines a set of data models and related custom operation procedures for the enhanced coverage restriction control request. The corresponding JSON schema for the representation of the operations defined by the ECRControl API is provided in its complete form in Annex A.12.
5.12.2 Data model
5.12.2.1 Data types
5.12.2.1.1 Introduction
This clause defines data structures to be used in the request and response.
Table 5.12.2.1.1-1 specifies data types re-used by the ECRControl API from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the ECRControl API.
Table 5.12.2.1.1-1: ECRControl API re-used Data Types
Data type |
Reference |
Comments |
EcRestrictionDataWb |
3GPP TS 29.503 [63] |
|
SupportedFeatures |
3GPP TS 29.571 [45] |
Used to negotiate the applicability of the optional features defined in table 5.12.4-1. |
Table 5.12.2.1.1-2 specifies the data types defined for the ECRControl API.
Table 5.12.2.1.1-2: ECRControl API specific Data Types
Data type |
Clause defined |
Description |
Applicability |
ECRControl |
5.12.2.1.2 |
Represents the parameters to request Enhanced Coverage Restriction control. |
|
ECRData |
5.12.2.1.3 |
Represents the current visited PLMN (if any) and the current settings of enhanced coverage restriction. |
|
PlmnEcRestrictionDataWb |
5.12.2.1.4 |
Indicates whether enhanced coverage mode is restricted or not for a PLMN ID. |
ECR_WB_5G |
5.12.2.1.2 Type: ECRControl
This type represents the Enhanced Coverage Restriction control request. The structure is used only for request.
Table 5.12.2.1.2-1: Definition of type ECRControl
Attribute name |
Data type |
Cardinality |
Description |
Applicability (NOTE 1) |
supportedFeatures |
SupportedFeatures |
1 |
Used to negotiate the supported optional features of the API as described in clause 5.2.7. |
|
mtcProviderId |
string |
0..1 |
Identifier the MTC Service Provider and/or MTC Application. (NOTE 4). |
|
scsAsId |
string |
0..1 |
Identifier of the SCS/AS. |
|
externalId |
ExternalId |
0..1 |
Identifies a user as defined in Clause 4.6.2 of 3GPP TS 23.682 [2]. (NOTE 2) |
|
msisdn |
Msisdn |
0..1 |
Identifies the MS internal PSTN/ISDN number allocated for a UE. (NOTE 2) |
|
ecrDataWbs |
array(PlmnEcRestrictionDataWb) |
0..N |
Identifies whether enhanced coverage mode are restricted or not. This attribute shall not be present for the query custom operation. |
ECR_WB_5G |
restrictedPlmnIds |
array(PlmnId) |
0..N |
Indicates a complete list (and possibly empty) of serving PLMNs where Enhanced Coverage shall be restricted. This attribute shall not be present for the query custom operation. (NOTE 3) |
|
allowedPlmnIds |
array(PlmnId) |
0..N |
Indicates a complete list (and possibly empty) of serving PLMNs where Enhanced Coverage shall be allowed. This attribute shall not be present for the query custom operation. (NOTE 3) |
|
NOTE 1: Properties marked with a feature as defined in clause 5.4.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: One of the properties "externalId" or "msisdn" shall be included. NOTE 3: "restrictedPlmnIds" and "allowedPlmnIds" shall be mutually exclusive. NOTE 4: The SCEF should check received MTC provider identifier and then the SCEF may: |
5.12.2.1.3 Type: ECRData
This data type represents the current visited PLMN (if any) and the current settings of enhanced coverage restriction. The structure is used only for response.
Table 5.12.2.1.3-1: Definition of type ECRData
Attribute name |
Data type |
Cardinality |
Description |
Applicability (NOTE 1) |
supportedFeatures |
SupportedFeatures |
1 |
Used to negotiate the supported optional features of the API as described in clause 5.2.7. |
|
visitedPlmnId |
PlmnId |
0..1 |
Indicates the current visited PLMN. |
|
ecrDataWbs |
array(PlmnEcRestrictionDataWb) |
0..N |
Identifies whether enhanced coverage mode are restricted or not. |
ECR_WB_5G |
restrictedPlmnIds |
array(PlmnId) |
0..N |
Indicates a complete list (and possibly empty) of serving PLMNs where Enhanced Coverage shall be restricted. (NOTE 2) |
|
allowedPlmnIds |
array(PlmnId) |
0..N |
Indicates a complete list (and possibly empty) of serving PLMNs where Enhanced Coverage shall be allowed. (NOTE 2) |
|
NOTE 1: Properties marked with a feature as defined in clause 5.4.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: "restrictedPlmnIds" and "allowedPlmnIds" shall be mutually exclusive. |
5.12.2.1.4 Type: PlmnEcRestrictionDataWb
Table 5.12.2.1.4-1: Definition of type PlmnEcRestrictionDataWb
Attribute name |
Data type |
Cardinality |
Description |
Applicability |
plmnId |
PlmnId |
1 |
Indicates the PLMN where enhanced coverage mode shall be restricted or not. |
|
plmnEcrDataWb |
EcRestrictionDataWb |
0..1 |
Identifies whether enhanced coverage mode are restricted or not. |
5.12.3 Custom Operations without associated resources
5.12.3.1 Overview
Custom operations used for this API are summarized in table 5.12.3.1-1. "apiRoot" is set as described in clause 5.2.4.
Table 5.12.3.1-1: Custom operations without associated resources
Operation name |
Custom operation URI |
Mapped HTTP method |
Description |
query |
/query |
POST |
Query the status of enhanced converage restriction for a UE |
configure |
/configure |
POST |
Configure the enhanced converage restriction for a UE |
5.12.3.2 Operation: query
5.12.3.2.1 Description
This custom operation allows an SCS/AS to query the current status of enhanced converage restriction for a UE via the T8 interface as defined in 3GPP TS 23.682 [2].
5.12.3.2.2 Operation Definition
This operation shall support the URI query parameters, request and response data structures, and response codes, as specified in the table 5.12.3.2.2-1 and table 5.12.3.2.2-2.
Table 5.12.3.2.2-1: URI query parameters supported by the POST on this operation
Name |
Data type |
Cardinality |
Remarks |
none specified |
Table 5.12.3.2.2-2: Data structures supported by the POST request/response on this operation
Request body |
Data type |
Cardinality |
Remarks |
|
ECRControl |
1 |
Parameters to query the current status of Enhanced Coverage Restriction. |
||
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
ECRData |
1 |
200 OK |
The requested information was returned successfully. |
|
none |
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. |
||
none |
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. |
||
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.12.5.3. |
Table 5.12.3.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 SCEF. |
Table 5.12.3.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 SCEF. |
5.12.3.3 Operation: configure
5.12.3.3.1 Description
This custom operation allows an SCS/AS to configure the current setting of enhanced converage restriction for a UE via the T8 interface as defined in 3GPP TS 23.682 [2].
5.12.3.3.2 Operation Definition
This operation shall support the request data structures specified in table 5.12.3.3.2-1 and the response data structure and response codes specified in table 5.12.3.3.2-2.
Table 5.12.3.3.2-1: URI query parameters supported by the POST on this operation
Name |
Data type |
Cardinality |
Remarks |
none specified |
Table 5.12.3.3.2-2: Data structures supported by the POST request/response on this operation
Request body |
Data type |
Cardinality |
Remarks |
|
ECRControl |
1 |
Parameters to configure the setting of Enhanced Coverage Restriction. |
||
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
ECRData |
1 |
200 OK |
The Enhanced Coverage Restriction setting was configured successfully |
|
none |
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. |
||
none |
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. |
||
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.12.5.3. |
Table 5.12.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.12.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.12.4 Used Features
The table below defines the features applicable to the ECRControl API. Those features are negotiated as described in clause 5.2.7.
Table 5.12.4-1: Features used by ECRControl API
Feature Number |
Feature |
Description |
1 |
ECR_WB_5G |
The enhanced coverage restriction control information indicates whether the enhanced coverage modes are restricted or not for the WB UE. The feature is not applicable to the pre-5G. |
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.12.5 Error handling
5.12.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.12.5.2 Protocol Errors
In this release of the specification, there are no additional protocol errors applicable for the ECRControl API.
5.12.5.3 Application Errors
The application errors defined for the ECRControl API are listed in table 5.12.5.3-1.
Table 5.12.5.3-1: Application errors
Application Error |
HTTP status code |
Description |
QUOTA_EXCEEDED |
403 Forbidden |
Not enough quota for SCS/AS. |