5.16 RacsParameterProvisioning API
29.1223GPPRelease 18T8 reference point for Northbound APIsTS
5.16.1 Overview
The RacsParameterProvisioning API is a RESTful API that allows the SCS/AS to provision manufacturer specific UE radio capability parameters. The RacsParameterProvisioning API defines a set of data models, resources and the related procedures for the creation and management of the parameters. The corresponding JSON schema for the representation of the resources and operations defined by the RacsParameterProvisioning API is provided in its complete form in Annex A.16.
5.16.2 Data model
5.16.2.1 Resource data types
5.16.2.1.1 Introduction
This clause defines data structures to be used in resource representations.
Table 5.16.2.1.1-1 specifies data types re-used by the RacsParameterProvisioning API from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the RacsParameterProvisioning API.
Table 5.16.2.1.1-1: RacsParameterProvisioning API re-used Data Types
|
Data type |
Reference |
Comments |
|
SupportedFeatures |
3GPP TS 29.571 [45] |
Used to negotiate the applicability of the optional features defined in table 5.16.4-1. |
|
TypeAllocationCode |
3GPP TS 29.571 [45] |
Used to signal UE model’s IMEI-TAC values in table 5.16.2.1.4-1. |
Table 5.16.2.1.1-2 specifies the data types defined for the RacsParameterProvisioning API.
Table 5.16.2.1.1-2: RacsParameterProvisioning API specific Data Types
|
Data type |
Clause defined |
Description |
Applicability |
|
RacsConfiguration |
5.16.2.1.4 |
Represents a single UE radio capability configuration data. |
|
|
RacsConfigurationRm |
5.16.2.1.6 |
Represents the same as the RacsConfiguration data type but with the "nullable: true" property. |
|
|
RacsFailureCode |
5.16.2.2.3 |
Represents the failure result of UE radio capability provisioning. |
|
|
RacsFailureReport |
5.16.2.1.3 |
Represents a radio capability data provisioning failure report. |
|
|
RacsProvisioningData |
5.16.2.1.2 |
Represents a UE’s radio capability data. |
|
|
RacsProvisioningDataPatch |
5.16.2.1.5 |
Represents parameters to request the modification of a UE’s radio capability data. |
5.16.2.1.2 Type: RacsProvisioningData
This type represents a UE radio capability data provided by the SCS/AS to the SCEF.
Table 5.16.2.1.2-1: Definition of type RacsProvisioningData
|
Attribute name |
Data type |
Cardinality |
Description |
Applicability (NOTE) |
|
self |
Link |
0..1 |
Link to the resource "Individual RACS parameter provisioning". 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. |
|
|
racsConfigs |
map(Racs Configuration) |
1..N |
Identifies the configuration related to manufacturer specific UE radio capability. Each element uniquely identifies an RACS configuration for an RACS ID and is identified in the map via the RACS ID as key. The response shall include successfully provisioned RACS data. |
|
|
racsReports |
map(RacsFailureReport) |
0..N |
Supplied by the SCEF. Contains the RACS IDs for which the RACS data are not provisioned successfully. Any string value can be used as a key of the map. |
|
|
NOTE: Properties marked with a feature as defined in clause 5.16.4 are applicable as described in clause 5.2.7. If no features are indicated, the related property applies for all the features. |
||||
5.16.2.1.3 Type: RacsFailureReport
This type represents a radio capability data provisioning report provided by the SCEF.
Table 5.16.2.1.3-1: Definition of type RacsFailureReport
|
Attribute name |
Data type |
Cardinality |
Description |
Applicability (NOTE) |
|
racsIds |
array(string) |
1..N |
Identifies the RACS ID(s) for which the RACS data are not provisioned successfully. |
|
|
failureCode |
RacsFailureCode |
1 |
It indicates the failure reason. |
|
|
NOTE: Properties marked with a feature as defined in clause 5.16.4 are applicable as described in clause 5.2.7. If no features are indicated, the related property applies for all the features. |
||||
5.16.2.1.4 Type: RacsConfiguration
This type represents a single UE radio capability configuration data provided by the SCS/AS to the SCEF.
Table 5.16.2.1.4-1: Definition of type RacsConfiguration
|
Attribute name |
Data type |
Cardinality |
Description |
Applicability (NOTE 1) |
|
racsId |
string |
1 |
The UE radio capability ID provided by the SCS/AS to identify the UE radio capability data. See 3GPP TS 23.003 [14] for the encoding. (NOTE 3) |
|
|
racsParamEps |
string |
0..1 |
The UE radio capability data in EPS, its encoding shall comply with the UE-CapabilityRAT-ContainerList as defined in clause 6.3.6 of 3GPP TS 36.331 [59]. (NOTE 2, NOTE 4) |
|
|
racsParam5Gs |
string |
0..1 |
The UE radio capability data in 5GS, its encoding shall comply with the UE-CapabilityRAT-ContainerList as defined in clause 6.3.3 of 3GPP TS 38.331 [60]. (NOTE 2, NOTE 4) |
|
|
imeiTacs |
array(TypeAllocationCode) |
1..N |
Related UE model’s IMEI-TAC values |
|
|
NOTE 1: Properties marked with a feature as defined in clause 5.16.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: At least one of racsParamEps or racsParam5Gs shall be provided. NOTE 3: A racsId shall only belong to one "Individual RACS Parameter Provisioning" resource. NOTE 4: UTRAN capabilities shall not be included within the "racsParamEps" attribute and/or the "racsParam5Gs" attribute. |
||||
5.16.2.1.5 Type: RacsProvisioningDataPatch
This type represents a UE radio capability data provided by the SCS/AS to the SCEF. This structure is used in the PATCH request.
Table 5.16.2.1.5-1: Definition of type RacsProvisioningDataPatch
|
Attribute name |
Data type |
Cardinality |
Description |
Applicability (NOTE) |
|
racsConfigs |
map(RacsConfigurationRm) |
0..N |
Identifies the configuration related to manufactuer specific UE radio capability. Each element uniquely identifies an RACS configuration for an RACS ID and is identified in the map via the RACS ID as key. |
|
|
NOTE: Properties marked with a feature as defined in clause 5.16.4 are applicable as described in clause 5.2.7. If no features are indicated, the related property applies for all the features. |
||||
5.16.2.1.6 Type: RacsConfigurationRm
This type represents a single UE radio capability configuration data provided by the SCS/AS to the SCEF. It is defined with "nullable: true" property.
Table 5.16.2.1.6-1: Definition of type RacsConfigurationRm
|
Attribute name |
Data type |
Cardinality |
Description |
Applicability |
|
racsParamEps |
string |
0..1 |
The UE radio capability data in EPS, its encoding shall comply with the UE-CapabilityRAT-ContainerList as defined in clause 6.3.6 of 3GPP TS 36.331 [59]. |
|
|
racsParam5Gs |
string |
0..1 |
The UE radio capability data in 5GS, its encoding shall comply with the UE-CapabilityRAT-ContainerList as defined in clause 6.3.3 of 3GPP TS 38.331 [60]. |
|
|
imeiTacs |
array(TypeAllocationCode) |
0..N |
Related UE model’s IMEI-TAC values. |
5.16.2.2 Referenced simple data types and enumerations
5.16.2.2.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.16.2.2.2 Simple data types
The simple data types defined in table 5.16.2.2.2-1 shall be supported.
Table 5.16.2.2.2-1: Simple data types
|
Type name |
Description |
5.16.2.2.3 Enumeration: RacsFailureCode
The enumeration RacsFailureCode represents the failure result of UE radio capability provisioning.
Table 5.16.2.2.3-1: Enumeration RacsFailureCode
|
Enumeration value |
Description |
Applicability |
|
MALFUNCTION |
This value indicates that something functions wrongly in RACS provisioning or the RACS provisioning does not function at all. |
|
|
RESOURCE_LIMITATION |
This value indicates there is resource limitation for RACS data storage. |
|
|
RACS_ID_DUPLICATED |
The received RACS identifier(s) are already provisioned. |
|
|
OTHER_REASON |
Other reason unspecified. |
5.16.3 Resource structure
5.16.3.1 General
All resource URIs of this API should have the following root:
{apiRoot}/3gpp-racs-pp/v1
"apiRoot" is set as described in clause 5.2.4. "apiName" shall be set to "3gpp-racs-pp" and "apiVersion" shall be set to "v1" for the version defined in the present document. 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.16.3.1-1: Resources and methods overview
|
Resource name |
Resource URI |
HTTP method |
Meaning |
|
RACS Parameter Provisionings |
/{scsAsId}/provisionings |
GET |
Read all RACS parameter provisionings for a given AF |
|
POST |
Create a new RACS parameter provisioning |
||
|
Individual RACS Parameter Provisioning |
/{scsAsId}/provisionings/{provisioningId} |
PUT |
Modify all properties in an existing RACS parameter provisioning |
|
PATCH |
Modify some properties in an existing RACS parameter provisioning |
||
|
GET |
Read an existing RACS parameter provisioning |
||
|
DELETE |
Delete a RACS parameter provisioning |
5.16.3.2 Resource: RACS Parameter Provisionings
5.16.3.2.1 Introduction
This resource allows an SCS/AS to read all active RACS parameter provisionings or create a new RACS parameter provisioning.
5.16.3.2.2 Resource definition
Resource URI: {apiRoot}/3gpp-racs-pp/v1/{scsAsId}/provisionings
This resource shall support the resource URI variables defined in table 5.16.3.2.2-1.
Table 5.16.3.2.2-1: Resource URI variables for resource "Parameter Provisioning"
|
Name |
Data type |
Definition |
|
apiRoot |
string |
See clause 5.2.4. |
|
scsAsId |
string |
Identifier of the SCS/AS. |
5.16.3.2.3 Resource methods
5.16.3.2.3.1 GET
The GET method allows to read all active RACS parameter provisionings indicated by the resource URI as defined in clause 5.16.3.2.2. 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.16.3.2.3.1-1 and table 5.16.3.2.3.1-2.
Table 5.16.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.16.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(RacsProvisioningData) |
0..N |
200 OK |
The provisioning 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.16.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.16.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.16.3.2.3.2 PUT
This HTTP method is not supported for the resource.
5.16.3.2.3.3 PATCH
This HTTP method is not supported for the resource.
5.16.3.2.3.4 POST
The POST method creates a new parameter provisioning resource for a given SCS/AS. The SCS/AS shall initiate the HTTP POST request message and the SCEF shall respond to the message. The SCEF shall construct the URI of the created resource.
This method shall support the URI query parameters, request and response data structures, and response codes, as specified in the table 5.16.3.2.3.4-1 and table 5.16.3.2.3.4-2.
Table 5.16.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.16.3.2.3.4-2: Data structures supported by the POST request/response by the resource
|
Request body |
Data type |
Cardinality |
Remarks |
|
|
RacsProvisioningData |
1 |
Parameters to create a new provisioning. |
||
|
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
|
RacsProvisioningData |
1 |
201 Created |
The provisioning was created successfully. The URI of the created resource shall be returned in the "Location" HTTP header. |
|
|
array(RacsFailureReport) |
1..N |
500 Internal Server Error |
The RACS data for all RACS IDs were not provisioned successfully. |
|
|
NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 also apply. |
||||
Table 5.16.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-racs-pp/v1/{scsAsId}/provisionings/{provisioningId} |
5.16.3.2.3.5 DELETE
This HTTP method is not supported for the resource.
5.16.3.3 Resource: Individual RACS Parameter Provisioning
5.16.3.3.1 Introduction
This resource allows an SCS/AS to query, update and delete a parameter provisioning indicated by the resource URI as defined in clause 5.16.3.3.2.
5.16.3.3.2 Resource definition
Resource URI: {apiRoot}/3gpp-racs-pp/v1/{scsAsId}/provisionings/{provisioningId}
This resource shall support the resource URI variables defined in table 5.16.3.3.2-1.
Table 5.16.3.2.2-1: Resource URI variables for resource "Individual RACS Parameter Provisioning"
|
Name |
Data type |
Definition |
|
apiRoot |
string |
See clause 5.2.4. |
|
scsAsId |
string |
Identifier of the SCS/AS of type ScsAsId. |
|
provisioningId |
string |
Identifier of the provisioning resource of type string. |
5.16.3.3.3 Resource methods
5.16.3.3.3.1 GET
The GET method allows to read an active parameter provisioning indicated by the resource URI as defined in clause 5.16.3.3.2. 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.16.3.3.3.1-1 and table 5.16.3.3.3.1-2.
Table 5.16.3.3.3.1-1: URI query parameters supported by the GET method on this resource
|
Name |
Data type |
Cardinality |
Remarks |
Table 5.16.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 |
|
RacsProvisioningData |
1 |
200 OK |
The provisioning 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.16.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.16.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.16.3.3.3.2 PATCH
The PATCH method shall be used to update some properties in an existing provisioning indicated by the Resource URI as defined in clause 5.16.3.3.2. 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, as specified in the table 5.16.3.3.3.2-1 and table 5.16.3.3.3.2-2.
Table 5.16.3.3.3.2-1: URI query parameters supported by the PATCH method on this resource
|
Name |
Data type |
Cardinality |
Remarks |
|
none specified |
Table 5.16.3.3.3.2-2: Data structures supported by the PATCH request/response by the resource
|
Request body |
Data type |
Cardinality |
Remarks |
|
|
RacsProvisioningDataPatch |
1 |
Partial update an existing parameter provisioning. |
||
|
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
|
RacsProvisioningData |
1 |
200 OK |
The provisioning data was updated successfully. The SCEF shall return an updated provisioning information in the response. |
|
|
none |
204 No Content |
The provisioning data was updated successfully, and no content is to be sent in the response message body. |
||
|
array(RacsFailureReport) |
1..N |
500 Internal Server Error |
The RACS data for all RACS IDs were not provisioned 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 PATCH method listed in table 5.2.6-1 also apply. |
||||
Table 5.16.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.16.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.16.3.3.3.3 PUT
The PUT method shall be used to update all properties in an existing provisioning indicated by the Resource URI as defined in clause 5.16.3.3.2. 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.16.3.3.3.3-1 and table 5.16.3.3.3.3-2.
Table 5.16.3.3.3.3-1: URI query parameters supported by the PUT method on this resource
|
Name |
Data type |
Cardinality |
Remarks |
|
none specified |
Table 5.16.3.3.3.3-2: Data structures supported by the PUT request/response by the resource
|
Request body |
Data type |
Cardinality |
Remarks |
|
|
RacsProvisioningData |
1 |
Replace an existing parameter provisioning. |
||
|
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
|
RacsProvisioningData |
1 |
200 OK |
The provisioning data was replaced successfully. The SCEF shall return an updated provisioning information in the response. |
|
|
none |
204 No Content |
The existing RACS Parameter Provisioning has been replaced successfully and no content is to be sent in the response message body. |
||
|
array(RacsFailureReport) |
1..N |
500 Internal Server Error |
The RACS data for all RACS IDs were not provisioned 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.16.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.16.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.16.3.3.3.4 POST
This HTTP method is not supported for the resource.
5.16.3.3.3.5 DELETE
The DELETE method deletes an existing provisioning resource "Individual RACS Parameter Provisioning". 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.16.3.3.3.5-1 and table 5.16.3.3.3.5-2.
Table 5.16.3.3.3.5-1: URI query parameters supported by the DELETE method on this resource
|
Name |
Data type |
Cardinality |
Remarks |
|
N/A |
Table 5.16.3.3.3.5-2: Data structures supported by the DELETE request/response on the resource
|
Request body |
Data type |
Cardinality |
Remarks |
|
|
none |
||||
|
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
|
none |
204 No Content |
The provisioning was terminated successfully. The response body shall be empty. |
||
|
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.16.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.16.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.16.4 Used Features
The table below defines the features applicable to the RacsParameterProvisioning API. Those features are negotiated as described in clause 5.2.7.
Table 5.16.4-1: Features used by RacsParameterProvisioning API
|
Feature Number |
Feature |
Description |
|
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.16.5 Error handling
5.16.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.16.5.2 Protocol Errors
In this release of the specification, there are no additional protocol errors applicable for the RacsParameterProvisioning API.
5.16.5.3 Application Errors
The application errors defined for the RacsParameterProvisioning API are listed in table 5.16.5.3-1.
Table 5.16.5.3-1: Application errors
|
Application Error |
HTTP status code |
Description |