5.22 ASTI API
29.5223GPP5G SystemNetwork Exposure Function Northbound APIsRelease 18Stage 3TS
5.22.1 Resources
5.22.1.1 Overview
All resource URIs of this API should have the following root:
{apiRoot}/3gpp-asti/v1
"apiRoot" is set as described in clause 5.2.4 in 3GPP TS 29.122 [4]. "apiName" shall be set to "3gpp-asti" and "apiVersion" shall be set to "v1" for the current version defined in the present document. All resource URIs in the clauses below are defined relative to the above root URI.
This clause describes the structure for the Resource URIs as shown in figure 5.22.1.1-1 and the resources and HTTP methods used for the ASTI API.
Figure 5.22.1.1-1: Resource URI structure of the ASTI API
Table 5.22.1.1-1 provides an overview of the resources and HTTP methods applicable for the ASTI API.
Table 5.22.1.1-1: Resources and methods overview
|
Resource name |
Resource URI |
HTTP method |
Description |
|
ASTI Configurations |
/{afId}/configurations |
GET |
Read all configurations of 5G access stratum time distribution for a given AF and subscription. |
|
POST |
Create a new configuration of 5G access stratum time distribution. |
||
|
/{afId}/configurations/retrieve |
retrieve (POST) |
Retrieval of the status of access stratum time distribution. |
|
|
Individual ASTI Configuration |
/{afId}/configurations/{configId} |
PUT |
Modify a configuration configuration of 5G access stratum time distribution. |
|
DELETE |
Delete a configuration of 5G access stratum time distribution. |
||
|
GET |
Query the status of the access time distribution |
5.22.1.2 Resource: ASTI Configurations
5.22.1.2.1 Introduction
This resource allows an AF to read all active configurations of 5G access stratum time distribution for a given AF, or allows an AF to create a new new configuration of 5G access stratum time distribution.
5.22.1.2.2 Resource Definition
Resource URI: {apiRoot}/3gpp-asti/v1/{afId}/configurations
This resource shall support the resource URI variables defined in table 5.22.1.2.2-1.
Table 5.22.1.2.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
Clause 5.2.4 of 3GPP TS 29.122 [4]. |
|
afId |
string |
Identifier of the AF. |
5.22.1.2.3 Resource Methods
5.22.1.2.3.1 General
The following clauses specify the resource methods supported by the resource as described in clause 5.22.1.2.2.
5.22.1.2.3.2 GET
The GET method allows to read all active configurations of 5G access stratum time distribution for a given AF and subscription. The AF shall initiate the HTTP GET request message and the NEF shall respond to the message.
This method shall support the URI query parameters specified in table 5.22.1.2.3.2-1.
Table 5.22.1.2.3.2-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 5.22.1.2.3.2-2 and the response data structures and response codes specified in table 5.22.1.2.3.2-3.
Table 5.22.1.2.3.2-2: Data structures supported by the GET Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
N/A |
Table 5.22.1.2.3.2-3: Data structures supported by the GET Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
array(AccessTimeDistributionData) |
M |
0..N |
200 OK |
The configuration information for the AF are returned. |
|
N/A |
307 Temporary Redirect |
Temporary redirection, during configuration retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
N/A |
308 Permanent Redirect |
Permanent redirection, during configuration retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
NOTE: The mandatory HTTP error status codes for the GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. |
||||
Table 5.22.1.2.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 NEF. |
Table 5.22.1.2.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 NEF. |
5.22.1.2.3.3 POST
The POST method creates a new configuration of 5G access stratum time distribution for a given AF. The AF shall initiate the HTTP POST request message and the NEF shall respond to the message. The NEF shall construct the URI of the created resource.
This method shall support the request data structures specified in table 5.22.1.2.3.3-1 and the response data structures and response codes specified in table 5.22.1.2.3.3-2.
Table 5.22.1.2.3.3-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
AccessTimeDistributionData |
M |
1 |
Parameters to create a configuration of 5G access stratum time distribution. |
Table 5.22.1.2.3.3-2: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
AccessTimeDistributionData |
M |
1 |
201 Created |
The configuration was created successfully. The URI of the created resource shall be returned in the "Location" HTTP header. |
|
NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. |
||||
Table 5.22.1.2.3.3-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-asti/v1/{afId}/configurations/{configId} |
5.22.1.2.4 Resource Custom Operations
5.22.1.2.4.1 Overview
Table 5.22.1.2.4.1-1: Custom operations
|
Operation Name |
Custom operation URI |
Mapped HTTP method |
Description |
|
retrieve |
/configurations/retrieve |
retrieve (POST) |
Request the status of the 5G access stratum time distribution for a list of UEs. |
5.22.1.2.4.2 Operation: retrieve
5.22.1.2.4.2.1 Description
This custom operation retrieves the status of the access stratum time distribution for a list of UEs.
5.22.1.2.4.2.2 Operation Definition
This operation shall support the request data structures specified in table 5.22.1.2.4.2.2-1 and the response data structure and response codes specified in table 5.22.1.2.4.2.2-2.
Table 5.22.1.2.4.2.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
StatusRequestData |
M |
1 |
Parameters to be sent by the NF service consumer when the status of the 5G access stratum time distribution for a list of UEs is requested. |
Table 5.22.1.2.4.2.2-2: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
StatusResponseData |
M |
1 |
200 OK |
Status of the 5G access stratum time distribution for a list of UEs is returned. |
|
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] shall also apply. |
||||
5.22.1.3 Resource: Individual ASTI Configuration
5.22.1.3.1 Introduction
This resource allows an AF to read/modify/cancel a configuration of 5G access stratum time distribution with the NEF.
5.22.1.3.2 Resource Definition
Resource URI: {apiRoot}/3gpp-asti/v1/{afId}/configurations/{configId}
This resource shall support the resource URI variables defined in table 5.22.1.3.2-1.
Table 5.22.1.3.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
Clause 5.2.4 of 3GPP TS 29.122 [4]. |
|
afId |
string |
Identifier of the AF. |
|
configId |
string |
Identifier of the configuration resource. |
5.22.1.3.3 Resource Methods
5.22.1.3.3.1 General
The following clauses specify the resource methods supported by the resource as described in clause 5.22.1.3.2.
5.22.1.3.3.2 GET
The GET method allows to read the active configuration for a given AF and configuration Id. The AF shall initiate the HTTP GET request message and the NEF shall respond to the message.
This method shall support the URI query parameters specified in table 5.22.1.3.3.2-1.
Table 5.22.1.3.3.2-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 5.22.1.3.3.2-2 and the response data structures and response codes specified in table 5.22.1.3.3.2-3.
Table 5.22.1.3.3.2-2: Data structures supported by the GET Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
N/A |
Table 5.22.1.3.3.2-3: Data structures supported by the GET Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
AccessTimeDistributionData |
M |
1 |
200 OK |
The configuration information for the AF in the request URI are returned. |
|
N/A |
307 Temporary Redirect |
Temporary redirection, during configuration retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
N/A |
308 Permanent Redirect |
Permanent redirection, during configuration retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
NOTE: The mandatory HTTP error status codes for the GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. |
||||
Table 5.22.1.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 NEF. |
Table 5.22.1.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 NEF. |
5.22.1.3.3.3 PUT
The PUT method modifies an existing configuration resource to update a configuration. The AF shall initiate the HTTP PUT request message and the NEF shall respond to the message.
This method shall support the request data structures specified in table 5.22.1.3.3.3-1 and the response data structures and response codes specified in table 5.22.1.3.3.3-2.
Table 5.22.1.3.3.3-1: Data structures supported by the PUT Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
AccessTimeDistributionData |
M |
1 |
Modify an existing configuration of 5G access stratum time distribution. |
Table 5.22.1.3.3.3-2: Data structures supported by the PUT Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
AccessTimeDistributionData |
M |
1 |
200 OK |
The configuration was updated successfully. |
|
N/A |
204 No Content |
The configuration was updated successfully. |
||
|
N/A |
307 Temporary Redirect |
Temporary redirection, during configuration modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
N/A |
308 Permanent Redirect |
Permanent redirection, during configuration modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
NOTE: The mandatory HTTP error status codes for the PUT method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. |
||||
Table 5.22.1.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 NEF. |
Table 5.22.1.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 NEF. |
5.22.1.3.3.4 DELETE
The DELETE method deletes the configuration of 5G access stratum time distribution for a given AF. The AF shall initiate the HTTP DELETE request message and the NEF shall respond to the message.
This method shall support the URI query parameters specified in table 5.22.1.3.3.4-1.
Table 5.22.1.3.3.4-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 5.22.1.3.3.4-2 and the response data structures and response codes specified in table 5.22.1.3.3.4-3.
Table 5.22.1.3.3.4-2: Data structures supported by the DELETE Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
N/A |
Table 5.22.1.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 configuration was terminated successfully. |
||
|
N/A |
307 Temporary Redirect |
Temporary redirection, during configuration termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
N/A |
308 Permanent Redirect |
Permanent redirection, during configuration termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative NEF. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [4]. |
||
|
NOTE: The mandatory HTTP error status codes for the DELETE method listed in table 5.2.6-1 of 3GPP TS 29.122 [4] also apply. |
||||
Table 5.22.1.3.3.4-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 NEF. |
Table 5.22.1.3.3.4-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 NEF. |
5.22.2 Custom Operations without associated resources
None.
5.22.3 Notifications
None.
5.22.4 Data Model
5.22.4.1 General
This clause specifies the application data model supported by the ASTI API.
Table 5.22.4.1-1 specifies the data types defined for the ASTI API.
Table 5.22.4.1-1: ASTI API specific Data Types
|
Data type |
Clause defined |
Description |
Applicability |
|
AccessTimeDistributionData |
5.22.4.3.2 |
Contains the parameters for the creation of 5G access stratum time distribution configuration. |
|
|
ActiveUe |
5.22.4.3.5 |
Contains the UE identifier whose status of the access stratum time distribution is active and the optional requested time synchronization error budget. |
|
|
StatusRequestData |
5.22.4.3.3 |
Contains the parameters for retrieval of the status of the access stratum time distribution for a list of UEs. |
|
|
StatusResponseData |
5.22.4.3.4 |
Contains the parameters for the status of the access stratum time distribution for a list of UEs. |
5.22.4.2 Reused data types
The data types reused by the TimeSyncExposure API from other specifications are listed in table 5.22.4.2-1.
Table 5.22.4.2-1: Re-used Data Types
|
Data type |
Reference |
Comments |
|
AsTimeDistributionParam |
3GPP TS 29.565 [50] |
Contains the 5G access stratum time distribution parameters. |
|
ExternalGroupId |
3GPP TS 29.122 [4] |
External Group Identifier for a user group. |
|
Gpsi |
3GPP TS 29.571 [8] |
Identifies a GPSI. |
|
SupportedFeatures |
3GPP TS 29.571 [8] |
Used to negotiate the applicability of the optional features defined in table 5.22.5-1. |
5.22.4.3 Structured data types
5.22.4.3.1 Introduction
This clause defines the structured data types to be used in resource representations.
5.22.4.3.2 Type: AccessTimeDistributionData
Table 5.22.4.3.2-1: Definition of type AccessTimeDistributionData
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
gpsis |
array(Gpsi) |
C |
1..N |
Identifies a list of UE(s). (NOTE) |
|
|
exterGroupId |
ExternalGroupId |
C |
0.1 |
Represents a group of users. (NOTE) |
|
|
asTimeDisParam |
AsTimeDistributionParam |
M |
1 |
5G access stratum time distribution parameters |
|
|
suppFeat |
SupportedFeatures |
C |
0..1 |
Represents the features supported by the NF service consumer. This parameter shall be supplied by the NF service consumer in the POST request and the response that requested the creation of an Individual ASTI Configuration resource. |
|
|
NOTE: One of "gpsis" or "externalGroupId" attribute shall be provided. |
|||||
5.22.4.3.3 Type: StatusRequestData
Table 5.22.4.3.3-1: Definition of type StatusRequestData
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
gpsis |
array(Gpsi) |
M |
1..N |
Identifies a list of UE(s). |
5.22.4.3.4 Type: StatusResponseData
Table 5.22.4.3.4-1: Definition of type StatusResponseData
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
inactiveUes |
array(Gpsi) |
O |
1..N |
Indicate the UE(s) whose status of the access stratum time distribution is inactive. |
|
|
activeUes |
array(ActiveUe) |
O |
1..N |
Contains the UE identifier(s) whose status of the access stratum time distribution is active and the optional requested time synchronization error budget. |
5.22.4.3.5 Type: ActiveUe
Table 5.22.4.3.5-1: Definition of type ActiveUe
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
gpsi |
Gpsi |
M |
1 |
Indicate the UE whose status of the access stratum time distribution is active. |
|
|
timeSyncErrBdgt |
Uinteger |
O |
0..1 |
Indicates the time synchronization error budget in terms of time units of nanoseconds. |
5.22.4.4 Simple data types and enumerations
5.22.4.4.1 Introduction
This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses.
5.22.4.4.2 Simple data types
The simple data types defined in table 5.22.4.4.2-1 shall be supported.
Table 5.22.4.4.2-1: Simple data types
|
Type Name |
Type Definition |
Description |
Applicability |
5.22.5 Used Features
The table below defines the features applicable to the ASTI API. Those features are negotiated as described in clause 5.2.7 of 3GPP TS 29.122 [4].
Table 5.22.5-1: Features used by ASTI API
|
Feature number |
Feature Name |
Description |
5.22.6 Error handling
5.22.6.1 General
HTTP error handling shall be supported as specified in clause 5.2.6 of 3GPP TS 29.122 [4].
In addition, the requirements in the following clauses shall apply.
5.22.6.2 Protocol Errors
In this Release of the specification, there are no additional protocol errors applicable for the ASTI API.
5.22.6.3 Application Errors
The application errors defined for the ASTI API are listed in table 5.22.6.3-1.
Table 5.22.6.3-1: Application errors
|
Application Error |
HTTP status code |
Description |