5 Nucmf_Provisioning Service API
29.6753GPPRelease 18Stage 3TSUser Equipment (UE) radio capability provisioning service
5.1 Introduction
The UE radio capability provisioning service shall use the Nucmf_Provisioning API.
The API URI of the Nucmf_Provisioning API shall be:
{apiRoot}/<apiName>/<apiVersion>
The request URIs used in HTTP requests from the NF service consumer towards the NF service producer shall have the Resource URI structure defined in clause 4.4.1 of 3GPP TS 29.501 [5], i.e.:
{apiRoot}/<apiName>/<apiVersion>/<apiSpecificResourceUriPart>
with the following components:
– The {apiRoot} shall be set as described in 3GPP TS 29.501 [5].
– The <apiName> shall be "nucmf-provisioning".
– The <apiVersion> shall be "v1".
– The <apiSpecificResourceUriPart> shall be set as described in clause 5.3.
5.2 Usage of HTTP
5.2.1 General
HTTP/2, IETF RFC 7540 [11], shall be used as specified in clause 5.2 of 3GPP TS 29.500 [4].
HTTP/2 shall be transported as specified in clause 5.3 of 3GPP TS 29.500 [4].
The OpenAPI [6] specification of HTTP messages and content bodies for the Nucmf_Provisioning API is contained in Annex A.
5.2.2 HTTP standard headers
5.2.2.1 General
See clause 5.2.2 of 3GPP TS 29.500 [4] for the usage of HTTP standard headers.
5.2.2.2 Content type
JSON, IETF RFC 8259 [12], shall be used as content type of the HTTP bodies specified in the present specification as specified in clause 5.4 of 3GPP TS 29.500 [4]. The use of the JSON format shall be signalled by the content type "application/json".
JSON object used in the HTTP PATCH request shall be encoded according to "JSON Merge Patch" and shall be signalled by the content type "application/merge-patch+json", as defined in IETF RFC 7396 [16].
"Problem Details" JSON object shall be used to indicate additional details of the error in a HTTP response body and shall be signalled by the content type "application/problem+json", as defined in IETF RFC 7807 [13].
5.2.3 HTTP custom headers
The mandatory HTTP custom header fields specified in clause 5.2.3.2 of 3GPP TS 29.500 [4] shall be supported, and the optional HTTP custom header fields specified in clause 5.2.3.3 of 3GPP TS 29.500 [4] may be supported.
In this Release of the specification, no specific custom headers are defined for the Nucmf_Provisioning API.
5.3 Resources
5.3.1 Overview
This clause describes the structure for the Resource URIs and the resources and methods used for the service.
Figure 5.3.1-1 depicts the resource URIs structure for the Nucmf_Provisioning API.
Figure 5.3.1-1: Resource URI structure of the Nucmf_Provisioning API
Table 5.3.1-1 provides an overview of the resources and applicable HTTP methods.
Table 5.3.1-1: Resources and methods overview
|
Resource name |
Resource URI |
HTTP method or custom operation |
Description |
|
UE radio capability provisionings |
/provisionings |
POST |
Create a UE radio capability provisioning resource. |
|
Individual UE radio capability provisioning |
/provisionings/{provisioningId} |
GET |
Read an existing UE radio capability provisioning resource. |
|
PUT |
Modify an existing UE radio capability provisioning resource. |
||
|
PATCH |
Modify an existing UE radio capability provisioning resource. |
||
|
DELETE |
Remove an existing UE radio capability provisioning resource. |
5.3.2 Resource: UE radio capability provisionings (Collection)
5.3.2.1 Description
The UE radio capability provisionings resource represents all the provisionings that exist in the UE radio capability provisioning service at a given UCMF instance.
5.3.2.2 Resource Definition
Resource URI: {apiRoot}/nucmf-provisioning/<apiVersion>/provisionings
This resource shall support the resource URI variables defined in table 5.3.2.2-1.
Table 5.3.2.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
See clause 5.1. |
5.3.2.3 Resource Standard Methods
5.3.2.3.1 POST
This method shall support the URI query parameters specified in table 5.3.2.3.1-1.
Table 5.3.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.3.2.3.1-2 and the response data structures and response codes specified in table 5.3.2.3.1-3.
Table 5.3.2.3.1-2: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
RacsData |
M |
1 |
Contains information for the creation of an Individual UE radio capability provisioning resource. |
Table 5.3.2.3.1-3: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
RacsData |
M |
1 |
201 Created |
The creation of an Individual UE radio capability provisioning resource is confirmed and a representation of that resource is returned. |
|
array(RacsFailureReport) |
M |
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.7.1-1 of 3GPP TS 29.500 [4] also apply. |
||||
Table 5.3.2.3.1-4: 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}/nucmf-provisioning/<apiVersion>/provisionings/{provisioningId} |
5.3.2.4 Resource Custom Operations
None.
5.3.3 Resource: Individual UE radio capability provisioning (Document)
5.3.3.1 Description
The Individual UE radio capability provisioning resource represents a single provisioning that exist in the UE radio capability provisioning service at a given UCMF instance.
5.3.3.2 Resource Definition
Resource URI: {apiRoot}/nucmf-provisioning/<apiVersion>/provisionings/{provisioningId}
This resource shall support the resource URI variables defined in table 5.3.3.2-1.
Table 5.3.3.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
See clause 5.1. |
|
provisioningId |
string |
Identifies the individual UE radio capability resource in the UCMF. To enable the value to be used as part of a URI, the string shall only contain allowed characters according to the "lower-with-hyphen" naming convention defined in clause 5.1.3 of 3GPP TS 29.501 [5] and rules for a path segment defined in IETF RFC 3986 [14]. |
5.3.3.3 Resource Standard Methods
5.3.3.3.1 GET
This method shall support the URI query parameters specified in table 5.3.3.3.1-1.
Table 5.3.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.3.3.3.1-2 and the response data structures and response codes specified in table 5.3.3.3.1-3.
Table 5.3.3.3.1-2: Data structures supported by the GET Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
n/a |
Table 5.3.3.3.1-3: Data structures supported by the GET Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
RacsData |
M |
1 |
200 OK |
A representation of an Individual UE radio capability provisioning resource is returned. |
|
NOTE: The mandatory HTTP error status codes for the GET method listed in table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. |
||||
5.3.3.3.2 PUT
This method shall support the URI query parameters specified in table 5.3.3.3.2-1.
Table 5.3.3.3.2-1: URI query parameters supported by the PUT 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.3.3.3.2-2 and the response data structures and response codes specified in table 5.3.3.3.2-3.
Table 5.3.3.3.2-2: Data structures supported by the PUT Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
RacsData |
M |
1 |
Contains the modification of an Individual UE radio capability provisioning data. |
Table 5.3.3.3.2-3: Data structures supported by the PUT Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
RacsData |
M |
1 |
200 OK |
The Individual UE radio capability provisioning resource is modified and a representation of that resource is returned. |
|
array(RacsFailureReport) |
M |
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 PUT method listed in table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. |
||||
5.3.3.3.3 PATCH
This method shall support the URI query parameters specified in table 5.3.3.3.3-1.
Table 5.3.3.3.2-1: URI query parameters supported by the PATCH 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.3.3.3.3-2 and the response data structures and response codes specified in table 5.3.3.3.3-3.
Table 5.3.3.3.3-2: Data structures supported by the PATCH Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
RacsDataPatch |
M |
1 |
Contains the modification of an Individual UE radio capability provisioning data. |
Table 5.3.3.3.3-3: Data structures supported by the PATCH Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
RacsData |
M |
1 |
200 OK |
The Individual UE radio capability provisioning resource is modified and a representation of that resource is returned. |
|
array(RacsFailureReport) |
M |
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 PATCH method listed in table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. |
||||
5.3.3.3.4 DELETE
This method shall support the URI query parameters specified in table 5.3.3.3.4-1.
Table 5.3.3.3.4-1: URI query parameters supported by the DELETE 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.3.3.3.4-2 and the response data structures and response codes specified in table 5.3.3.3.4-3.
Table 5.3.3.3.4-2: Data structures supported by the DELETE Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
n/a |
Table 5.3.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 Individual UE radio capability resource was successfully removed. |
||
|
NOTE: The mandatory HTTP error status codes for the DELETE method listed in table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply. |
||||
5.4 Custom Operations without associated resources
No custom operation is defined in this Release of the specification.
5.5 Notifications
Notifications are not applicable for the current Release.
5.6 Data Model
5.6.1 General
This clause specifies the application data model supported by the API.
Table 5.6-1 specifies the data types defined for the Nucmf_Provisioning service based interface protocol.
Table 5.6-1: Nucmf_Provisioning specific Data Types
|
Data type |
Section defined |
Description |
Applicability |
|
RacsData |
5.6.2.2 |
UE radio capability data |
|
|
RacsDataPatch |
5.6.2.3 |
UE radio capability data for PATCH request |
Table 5.6-2 specifies data types re-used by the Nucmf_Provisioning service based interface protocol from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the Nucmf_Provisioning service based interface.
Table 5.6-2: Nucmf_Provisioning re-used Data Types
|
Data type |
Reference |
Comments |
Applicability |
|
RacsConfiguration |
3GPP TS 29.122 [15] |
Represents the UE radio capability data configuration. |
|
|
RacsConfigurationRm |
3GPP TS 29.122 [15] |
Represents the UE radio capability data configuration with "nullable: true" property. |
|
|
RacsFailureReport |
3GPP TS 29.122 [15] |
Represents the report for UE radio capability data provisioning. |
|
|
SupportedFeatures |
3GPP TS 29.122 [15] |
Used to negotiate the applicability of the optional features defined in table 5.8-1. |
5.6.2 Structured data types
5.6.2.1 Introduction
This clause defines the structures to be used in resource representations.
5.6.2.2 Type: RacsData
This type represents a UE radio capability data provided by the NF service consumer to the UCMF.
Table 5.6.2.2-1: Definition of type RacsData
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
suppFeat |
SupportedFeatures |
C |
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(RacsConfiguration) |
M |
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) |
O |
1..N |
Supplied by the UCMF. 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. |
5.6.2.3 Type: RacsDataPatch
This type represents a UE radio capability data provided by the NF service consumer to the UCMF.
Table 5.6.2.3-1: Definition of type RacsDataPatch
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
racsConfigs |
map(RacsConfigurationRm) |
O |
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. |
5.6.3 Simple data types and enumerations
5.6.3.1 Introduction
This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses.
5.6.3.2 Simple data types
The simple data types defined in table 5.6.3.2-1 shall be supported.
Table 5.6.3.2-1: Simple data types
|
Type Name |
Type Definition |
Description |
Applicability |
5.7 Error Handling
5.7.1 General
For the Nucmf_Provisioning API, HTTP error responses shall be supported as specified in clause 4.8 of 3GPP TS 29.501 [5]. Protocol errors and application errors specified in table 5.2.7.2-1 of 3GPP TS 29.500 [4] shall be supported for an HTTP method if the corresponding HTTP status codes are specified as mandatory for that HTTP method in table 5.2.7.1-1 of 3GPP TS 29.500 [4].
In addition, the requirements in the following clauses are applicable for the Nucmf_Provisioning API.
5.7.2 Protocol Errors
No specific procedures for the Nucmf_Provisioning service are specified.
5.7.3 Application Errors
The application errors defined for the Nucmf_Provisioning service are listed in table 5.7.3-1.
Table 5.7.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
5.8 Feature negotiation
The optional features in table 5.8-1 are defined for the Nucmf_Provisioning API. They shall be negotiated using the extensibility mechanism defined in clause 6.6.2 of 3GPP TS 29.500 [4].
Table 5.8-1: Supported Features
|
Feature number |
Feature Name |
Description |
5.9 Security
As indicated in 3GPP TS 33.501 [8] and 3GPP TS 29.500 [4], the access to the Nucmf_Provisioning API may be authorized by means of the OAuth2 protocol (see IETF RFC 6749 [9]), based on local configuration, using the "Client Credentials" authorization grant, where the NRF (see 3GPP TS 29.510 [10]) plays the role of the authorization server.
If OAuth2 is used, an NF service consumer, prior to consuming services offered by the Nucmf_Provisioning API, shall obtain a "token" from the authorization server, by invoking the Access Token Request service, as described in 3GPP TS 29.510 [10], clause 5.4.2.2.
NOTE: When multiple NRFs are deployed in a network, the NRF used as authorization server is the same NRF that the NF service consumer used for discovering the Nucmf_Provisioning service.
The Nucmf_Provisioning API defines a single scope "nucmf-provisioning" for the entire service, and it does not define any additional scopes at resource or operation level.
Annex A (normative):
OpenAPI specification