6.3 VAE_ApplicationRequirement API
29.4863GPPRelease 18Stage 3TSV2X Application Enabler (VAE) Services
6.3.1 Introduction
The VAE_ApplicationRequirement Service shall use the VAE_ApplicationRequirement API.
The API URI of the VAE_ApplicationRequirement API shall be:
{apiRoot}/<apiName>/<apiVersion>
The request URIs used in HTTP requests from the NF service consumer towards the VAE Server shall have the Resource URI structure defined in clause 4.4.1 of 3GPP TS 29.501 [3], i.e.:
{apiRoot}/<apiName>/<apiVersion>/<apiSpecificResourceUriPart>
with the following components:
– The {apiRoot} shall be set as described in 3GPP TS 29.501 [3].
– The <apiName> shall be "vae-app-req".
– The <apiVersion> shall be "v1".
– The <apiSpecificResourceUriPart> shall be set as described in clause 6.3.3.
6.3.2 Usage of HTTP
6.3.2.1 General
Support of HTTP/1.1 (IETF RFC 7230 [12], IETF RFC 7231 [13], IETF RFC 7232 [14], IETF RFC 7233 [15], IETF RFC 7234 [16] and IETF RFC 7235 [17]) over TLS is mandatory and support of HTTP/2 as specified in clause 5 of 3GPP TS 29.500 [2] is recommended. TLS shall be used as specified in 3GPP TS 33.536 [31] and 3GPP TS 33.501 [32]. A V2X application specific server desiring to use HTTP/2 shall use the HTTP upgrade mechanism to negotiate applicable HTTP version as described in IETF RFC 7540 [5].
HTTP/2, shall be transported as specified in clause 5.3 of 3GPP TS 29.500 [2].
An OpenAPI [6] specification of HTTP messages and content bodies for the VAE_ApplicationRequirement is contained in Annex A.4.
6.3.2.2 HTTP standard headers
6.3.2.2.1 General
See clause 5.2.2 of 3GPP TS 29.500 [2] for the usage of HTTP standard headers.
6.3.2.2.2 Content type
JSON, IETF RFC 8259 [7], 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 [2]. The use of the JSON format shall be signalled by the content type "application/json".
6.3.2.3 HTTP custom headers
6.3.2.3.1 General
The HTTP custom header fields specified in clause 5.2.8 of 3GPP TS 29.122 [22] may be applicable.
6.3.3 Resources
6.3.3.1 Overview
This clause describes the structure for the Resource URIs and the resources and methods used for the service.
Figure 6.3.3.1-1 depicts the resource URIs structure for the VAE_ApplicationRequirement API.
Figure 6.3.3.1-1: Resource URI structure of the VAE_ApplicationRequirement API
Table 6.3.3.1-1 provides an overview of the resources and applicable HTTP methods.
Table 6.3.3.1-1: Resources and methods overview
|
Resource name |
Resource URI |
HTTP method or custom operation |
Description |
|
Application Requirements |
/application-requirements |
POST |
Create a new Individual Application Requirement resource for a V2X UE or V2X group ID. |
|
Individual Application Requirement |
/application-requirements /{requirementId} |
GET |
Read an Individual Application Requirement resource. |
|
DELETE |
Delete an Individual Application Requirement resource. |
6.3.3.2 Resource: Application Requirements
6.3.3.2.1 Description
This resource represents the collection of the individual Application Requirement resources created in the VAE Server.
6.3.3.2.2 Resource Definition
Resource URI: {apiRoot}/vae-app-req/<apiVersion>/application-requirements
This resource shall support the resource URI variables defined in table 6.3.3.2.2-1.
Table 6.3.3.2.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
See clause 6.3.1 |
6.3.3.2.3 Resource Standard Methods
6.3.3.2.3.1 POST
This method shall support the URI query parameters specified in table 6.3.3.2.3.1-1.
Table 6.3.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 6.3.3.2.3.1-2 and the response data structures and response codes specified in table 6.3.3.2.3.1-3.
Table 6.3.3.2.3.1-2: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
ApplicationRequirementData |
M |
1 |
Parameters to create an individual Application Requirement resource. |
Table 6.3.3.2.3.1-3: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
ApplicationRequirementData |
O |
0..1 |
201 Created |
An individual Application Requirement resource for the V2X UE ID or the V2X group ID is created 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 [2] shall also apply. |
||||
Table 6.3.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}/vae-app-req/<apiVersion>/application-requirements/{requirementId} |
6.3.3.2.4 Resource Custom Operations
None.
6.3.3.3 Resource: Individual Application Requirement
6.3.3.3.1 Description
The individual Application Requirement resource represents an individual Application Requirement created in the VAE Server and associated with the V2X UE ID or V2X group ID.
6.3.3.3.2 Resource definition
Resource URI: {apiRoot}/vae-app-req/<apiVersion>/application-requirements/{requirementId}
This resource shall support the resource URI variables defined in table 6.2.3.3-1.
Table 6.3.3.3.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
See clause 6.3.1 |
|
requirementId |
string |
Unique identifier of the individual Application Requirement resource for the V2X UE ID or the V2X group ID. |
6.3.3.3.3 Resource Standard Methods
6.3.3.3.3.1 GET
This method shall support the URI query parameters specified in table 6.3.3.3.3.1-1.
Table 6.3.3.3.3.1-1: URI query parameters supported by the GET method on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
n/a |
This method shall support the request data structures specified in table 6.3.3.3.3.1-2 and the response data structures and response codes specified in table 6.3.3.3.3.1-3.
Table 6.3.3.3.3.1-2: Data structures supported by the GET Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
n/a |
Table 6.3.3.3.3.1-3: Data structures supported by the GET Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
ApplicationRequirementData |
M |
1 |
200 OK |
An individual Application Requirement resource for the V2X UE ID or V2X group ID is returned successfully. |
|
n/a |
307 Temporary Redirect |
Temporary redirection, during Individual Application Requirement retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative VAE Server. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [22] with the difference: SCEF is replaced by the VAE Server and the SCS/AS is replaced by the V2X application specific server. |
||
|
n/a |
308 Permanent Redirect |
Permanent redirection, during Individual Application Requirement retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative VAE Server. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [22] with the difference: SCEF is replaced by the VAE Server and the SCS/AS is replaced by the V2X application specific server. |
||
|
NOTE: The mandatory HTTP error status codes for the GET method listed in table 5.2.7.1-1 of 3GPP TS 29.500 [2] shall also apply. |
||||
Table 6.3.3.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 URI of the resource located in an alternative VAE Server. |
Table 6.3.3.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 URI of the resource located in an alternative VAE Server. |
6.3.3.3.3.2 DELETE
This method shall support the URI query parameters specified in table 6.3.3.3.3.2-1.
Table 6.3.3.3.3.2-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 6.3.3.3.3.2-2 and the response data structures and response codes specified in table 6.3.3.3.3.2-3.
Table 6.3.3.3.3.2-2: Data structures supported by the DELETE Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
n/a |
Table 6.3.3.3.3.2-3: Data structures supported by the DELETE Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
n/a |
204 No Content |
Individual Application Requirement resource was successfully deleted |
||
|
n/a |
307 Temporary Redirect |
Temporary redirection, during Individual Application Requirement deletion. The response shall include a Location header field containing an alternative URI of the resource located in an alternative VAE Server. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [22] with the difference: SCEF is replaced by the VAE Server and the SCS/AS is replaced by the V2X application specific server. |
||
|
n/a |
308 Permanent Redirect |
Permanent redirection, during Individual Application Requirement deletion. The response shall include a Location header field containing an alternative URI of the resource located in an alternative VAE Server. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [22] with the difference: SCEF is replaced by the VAE Server and the SCS/AS is replaced by the V2X application specific server. |
||
|
NOTE: The mandatory HTTP error status code for the DELETE method listed in table 5.2.7.1-1 of 3GPP TS 29.500 [5] also apply. |
||||
Table 6.3.3.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 VAE Server. |
Table 6.3.3.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 VAE Server. |
6.3.3.4 Resource Custom Operations
None.
6.3.4 Custom Operations without associated resources
There are no custom operations without associated resources supported on VAE_ApplicationRequirement.
6.3.5 Notifications
6.3.5.1 General
The VAE server and NF service consumer shall support the delivery of Notifications using a separate HTTP connection towards an address as assigned the NF service consumer described in clause 6.3.5.2.
A VAE server and NF service consumer may support testing a notification connection as described in clause 6.3.5.3. A VAE server and NF service consumer may support the delivery of Notification using Websocket (IETF RFC 6455 [21]) as described in clause 6.1.5.4.
6.3.5.2 Notification Delivery using a separate HTTP connection
The descriptions in clause 5.2.5.2 of 3GPP TS 29.122 [22] apply with following differences:
– description of SCS/AS applies to the NF service consumer;
– description of SCEF applies to the VAE server; and
– "notificationDestination" attribute is replaced by the "notifUri" attribute.
6.3.5.3 Notification Test Event
The descriptions in clause 5.2.5.3 of 3GPP TS 29.122 [22] apply with following differences:
– description of SCS/AS applies to the NF service consumer; and
– description of SCEF applies to the VAE server.
6.3.5.4 Notification Delivery using Websocket
The descriptions in clause 5.2.5.4 of 3GPP TS 29.122 [22] apply with following differences:
– description of SCS/AS applies to the NF service consumer; and
– description of SCEF applies to the VAE server.
6.3.5.5 Methods
Table 6.3.5.5-1: Methods
|
Callback URI |
HTTP method or custom operation |
Description (service operation) |
|
{notifUri} |
POST |
Notify the result of the network resource adaptation corresponding to the V2X application requirement. |
6.3.5.6 Notify Network Resource
6.3.5.6.1 Description
This notification is used by the VAE Server to notify the result of the network resource adaptation corresponding to the V2X application requirement.
6.3.5.6.2 Operation Definition
This operation shall support the request data structures specified in table 6.3.5.6.2-1 and the response data structure and response codes specified in table 6.3.5.6.2-2.
Table 6.3.5.6.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
AppReqNotification |
M |
1 |
Notify the result of the network resource adaptation corresponding to the V2X application requirement. |
Table 6.3.5.6.2-2: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
n/a |
204 No Content |
. |
||
|
n/a |
307 Temporary Redirect |
Temporary redirection, during the notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative V2X application specific server where the notification should be sent. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [22] with the difference: SCEF is replaced by the VAE Server and the SCS/AS is replaced by the V2X application specific server. |
||
|
n/a |
308 Permanent Redirect |
Permanent redirection, during the notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative V2X application specific server where the notification should be sent. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [22] with the difference: SCEF is replaced by the VAE Server and the SCS/AS is replaced by the V2X application specific server. |
||
|
NOTE 1: The mandatory HTTP error status codes for the POST method listed in table 5.2.7.1-1 of 3GPP TS 29.500 [4] shall also apply. |
||||
Table 6.3.5.6.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 representing the end point of an alternative V2X application specific server towards which the notification should be redirected. |
Table 6.3.5.6.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 representing the end point of an alternative V2X application specific server towards which the notification should be redirected. |
6.3.6 Data Model
6.3.6.1 General
This clause specifies the application data model supported by the API.
Table 6.3.6.1-1 specifies the data types defined for the VAE_ApplicationRequirement API.
Table 6.3.6.1-1: VAE_ApplicationRequirement specific Data Types
|
Data type |
Section defined |
Description |
Applicability |
|
ApplicationRequirement |
6.3.6.2.3 |
Represents the requirements for application change. |
|
|
ApplicationRequirementData |
6.3.6.2.2 |
Represents an individual Application Requirement resource for a V2X UE ID or a V2X group ID. |
|
|
AppReqNotification |
6.3.6.2.4 |
Represents a notificaton of the result of the network resource adaptation corresponding to the V2X application requirement. |
|
|
ReservationResult |
6.3.6.3.4 |
Represents the result of the network resource adaptation corresponding to the V2X application requirement. |
|
|
ServiceLevel |
6.3.6.3.3 |
Indicates a service level for application service. |
Table 6.3.6.1-2 specifies data types re-used by the VAE_ApplicationRequirement 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 VAE_ApplicationRequirement service based interface.
Table 6.3.6.1-2: VAE_ApplicationRequirement re-used Data Types
|
Data type |
Reference |
Comments |
Applicability |
|
DateTime |
3GPP TS 29.571 [11] |
Used to indicate a duration. |
|
|
SupportedFeatures |
3GPP TS 29.571 [11] |
Used to negotiate the applicability of the optional features. |
|
|
TestNotification |
3GPP TS 29.122 [22] |
Represents a notification that can be sent to test whether a chosen notification mechanism works. |
Notification_test_event |
|
Uri |
3GPP TS 29.571 [11] |
Used to indicate an URI. |
|
|
V2xGroupId |
6.1.6.3.2 |
Used to indicate an identifier of a V2X group. |
|
|
V2xServiceID |
6.1.6.3.2 |
The V2X service ID to which the V2X message belongs to |
|
|
V2xUeId |
6.1.6.3.2 |
Identifier of the destination V2X UE |
|
|
WebsockNotifConfig |
3GPP TS 29.122 [22] |
Pepresents configuration for the delivery of notifications over Websockets. |
Notification_websocket |
6.3.6.2 Structured data types
6.3.6.2.1 Introduction
This clause defines the structures to be used in resource representations.
6.3.6.2.2 Type: ApplicationRequirementData
Table 6.3.6.2.2-1: Definition of type ApplicationRequirementData
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
ueId |
V2xUeId |
O |
0..1 |
Indicates a UE ID for which the V2X message is addressed. (NOTE) |
|
|
groupId |
V2xGroupId |
O |
0..1 |
Indicates a group ID for which the V2X message is addressed. (NOTE) |
|
|
serviceId |
V2xServiceId |
M |
1 |
The V2X service ID for which application requirement corresponds to. |
|
|
appRequirement |
ApplicationRequirement |
M |
1 |
The requirement for application change. E.g. service levels for application service. |
|
|
notifUri |
Uri |
M |
1 |
Identifies the recipient of V2X application requirement notification sent by the VAE server. |
|
|
duration |
DateTime |
O |
0..1 |
Identifies the absolute time at which the related Individual Application Requirement resource is considered to expire. When omitted in the request, it indicates the resource is requested to be valid forever by the NF service consumer. When omitted in the response, it indicates the resource is set to valid forever by the VAE server |
|
|
requestTestNotification |
boolean |
O |
0..1 |
Set to true by the NF service consumer to request the VAE server to send a test notification as defined in clause 6.3.5.3. Set to false or omitted otherwise. |
Notification_test_event |
|
websockNotifConfig |
WebsockNotifConfig |
O |
0..1 |
Configuration parameters to set up notification delivery over Websocket protocol as defined in clause 6.3.5.4. |
Notification_websocket |
|
suppFeat |
SupportedFeatures |
C |
0..1 |
Indicates the features supported by the service consumer. It shall be included in the first interaction. |
|
|
NOTE: Either the "ueId" attribute or "groupId" attribute shall be included. |
|||||
6.3.6.2.3 Type: ApplicationRequirement
Table 6.3.6.2.3-1: Definition of type ApplicationRequirement
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
serviceLevel |
ServiceLevel |
O |
0..1 |
Indicates a service level for application service. |
6.3.6.2.4 Type: AppReqNotification
Table 6.3.6.2.4-1: Definition of type AppReqNotification
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
resourceUri |
Uri |
M |
1 |
The resource URI of the individual Application Requirement related to the notification. |
|
|
result |
ReservationResult |
M |
1 |
The result of the network resource adaptation corresponding to the V2X application requirement. |
6.3.6.3 Simple data types and enumerations
6.3.6.3.1 Introduction
This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses.
6.3.6.3.2 Simple data types
The simple data types defined in table 6.3.6.3.2-1 shall be supported.
Table 6.3.6.3.2-1: Simple data types
|
Type Name |
Type Definition |
Description |
Applicability |
6.3.6.3.3 Enumeration: ServiceLevel
Table 6.3.6.3.3-1: Enumeration ServiceLevel
|
Enumeration value |
Description |
Applicability |
|
HIGH |
Service level is high. |
|
|
MEDIUM |
Service level is medium. |
|
|
LOW |
Service level is low. |
6.3.6.3.4 Enumeration: ReservationResult
Table 6.3.6.3.4-1: Enumeration ReservationResult
|
Enumeration value |
Description |
Applicability |
|
SUCCESSFUL |
The resource reservation is successful. |
|
|
FAILURE |
The resource reservation is failure. |
6.3.7 Error Handling
6.3.7.1 General
HTTP error handling shall be supported as specified in clause 5.2.4 of 3GPP TS 29.500 [2].
For the VAE_ApplicationRequirement Service API, HTTP error responses shall be supported as specified in clause 4.8 of 3GPP TS 29.501 [3].
Protocol errors and application errors specified in table 5.2.7.2-1 of 3GPP TS 29.500 [2] 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 [2].
In addition, the requirements in the following clauses are applicable for the VAE_ApplicationRequirement Service API.
6.3.7.2 Protocol Errors
In this Release of the specification, there are no additional protocol errors applicable for the VAE_ApplicationRequirement API.
6.3.7.3 Application Errors
The application errors defined for the VAE_ApplicationRequirement service are listed in table 6.3.7.3-1.
Table 6.3.7.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
6.3.8 Feature negotiation
The optional features in table 6.3.8-1 are defined for the VAE_ApplicationRequirement API. They shall be negotiated using the extensibility mechanism defined in clause 6.6 of 3GPP TS 29.500 [2].
Table 6.3.8-1: Supported Features
|
Feature number |
Feature Name |
Description |
|
1 |
Notification_test_event |
The testing of notification connection is supported according to clause 6.3.5.3. |
|
2 |
Notification_websocket |
The delivery of notifications over Websocket is supported according to clause 6.3.5.4. This feature requires that the Notification_test_event feature is also supported. |