8.8 Eees_EELManagedACR API
29.5583GPPApplication Programming Interface (API) specificationEnabling Edge ApplicationsRelease 18Stage 3TS
8.8.1 Introduction
The Eees_EELManagedACR service shall use the Eees_ACRStatusUpdate API.
The API URI of the Eees_EELManagedACR API shall be:
{apiRoot}/<apiName>/<apiVersion>
The request URIs used in HTTP requests shall have the Resource URI structure defined in clause 5.2.4 of 3GPP TS 29.122 [6], i.e.:
{apiRoot}/<apiName>/<apiVersion>/<apiSpecificSuffixes>
with the following components:
– The {apiRoot} shall be set as described in clause 5.2.4 of 3GPP TS 29.122 [6].
– The <apiName> shall be "eees-eel-acr".
– The <apiVersion> shall be "v1".
– The <apiSpecificSuffixes> shall be set as described in clause 5.2.4 of 3GPP TS 29.122 [6].
8.8.2 Usage of HTTP
The provisions of clause 5.2.2 of 3GPP TS 29.122 [6] shall apply for the Eees_EELManagedACR API.
8.8.3 Resources
8.8.3.1 Overview
This clause describes the structure for the Resource URIs and the resources and methods used for the service.
Figure 8.8.3.1-1 depicts the resource URIs structure for the Eees_EELManagedACR API.
Figure 8.8.3.1-1: Resource URIs structure of the Eees_EELManagedACR API
Table 8.8.3.1-1 provides an overview of the resources and applicable HTTP methods for the Eees_EELManagedACR API.
Table 8.8.3.1-1: Resources and methods overview
|
Resource name |
Resource URI |
HTTP method or custom operation |
Description |
|
ACT Status Subscriptions |
/subscriptions |
GET |
Retrieve all the active ACT Status Subscription resources managed by the EES. |
|
POST |
Request the creation of a subscription to ACT status reporting during an EEL Managed ACR. |
||
|
Individual ACT Status Subscription |
/subscriptions/{subscriptionId} |
GET |
Retrieve an Individual ACT Status Subscription resource identified by the provided subscription identifier. |
8.8.3.2 Resource: ACT Status Subscriptions
8.8.3.2.1 Description
This resource represents the collection of ACT Status Subscriptions managed by the EES.
8.8.3.2.2 Resource Definition
Resource URI: {apiRoot}/eees-eel-acr/<apiVersion>/subscriptions
This resource shall support the resource URI variables defined in table 8.8.3.2.2-1.
Table 8.8.3.2.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
See clause 5.2.4 of 3GPP TS 29.122 [6]. |
8.8.3.2.3 Resource Standard Methods
The following clauses specify the standard methods supported by the resource.
8.8.3.2.3.1 GET
The GET method allows a service consumer to retrieve all the active ACT Status Subscriptions managed by the EES.This method shall support the URI query parameters specified in table 8.8.3.2.3.1-1.
Table 8.8.3.2.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 8.8.3.2.3.1-2 and the response data structures and response codes specified in table 8.8.3.2.3.1-3.
Table 8.8.3.2.3.1-2: Data structures supported by the GET Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
n/a |
Table 8.8.3.2.3.1-3: Data structures supported by the GET Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
array(ACTStatusSubsc) |
M |
0..N |
200 OK |
Successful case. All the active ACT Status Subscriptions managed by the EES are returned. |
|
n/a |
307 Temporary Redirect |
Temporary redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative EES. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [6]. |
||
|
n/a |
308 Permanent Redirect |
Permanent redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative EES. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [6]. |
||
|
NOTE: The mandatory HTTP error status code for the HTTP GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [6] also apply. |
||||
Table 8.8.3.2.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 EES. |
Table 8.8.3.2.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 EES. |
8.8.3.2.3.2 POST
The POST method allows a service consumer (i.e. T-EAS) to request the creation of a subscription to ACT status reporting at the EES (i.e. T-EES). This method shall support the URI query parameters specified in table 8.8.3.2.3.2-1.
Table 8.8.3.2.3.2-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 8.8.3.2.3.2-2 and the response data structures and response codes specified in table 8.8.3.2.3.2-3.
Table 8.8.3.2.3.2-2: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
ACTStatusSubsc |
M |
1 |
Represents the parameters to request the creation of a subscription to ACT status reporting. |
Table 8.8.3.2.3.2-3: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
ACTStatusSubsc |
M |
1 |
201 Created |
Successful case. The subscription is successfully created and a representation of the created Individual ACT Status Subscription resource is returned. An HTTP "Location" header that contains the resource URI of the created Individual ACT Status Subscription resource shall also be included. |
|
NOTE: The mandatory HTTP error status code for the HTTP POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [6] also apply. |
||||
Table 8.8.3.2.3.2-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}/eees-eel-act/<apiVersion>/subscriptions/{subscriptionId} |
8.8.3.2.4 Resource Custom Operations
There are no resource custom operations defined for this resource in this release of the specification.
8.8.3.3 Resource: Individual ACT Status Subscription
8.8.3.3.1 Description
This resource represents an Individual ACT Status subscription managed by the EES.
8.8.3.3.2 Resource Definition
Resource URI: {apiRoot}/eees-eel-acr/<apiVersion>/subscriptions/{subscriptionId}
This resource shall support the resource URI variables defined in table 8.8.3.3.2-1.
Table 8.8.3.3.2-1: Resource URI variables for this resource
|
Name |
Data type |
Definition |
|
apiRoot |
string |
See clause 5.2.4 of 3GPP TS 29.122 [6]. |
|
subscriptionId |
string |
Represents the subscription identifier. |
8.8.3.3.3 Resource Standard Methods
The following clauses specify the standard methods supported by the resource.
8.8.3.3.3.1 GET
The GET method allows a service consumer to retrieve an ACT status subscription identified by the subscription identifier included in the request URI (i.e. within the "/{subscriptionId}" path segment).This method shall support the URI query parameters specified in table 8.8.3.3.3.1-1.
Table 8.8.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 8.8.3.3.3.1-2 and the response data structures and response codes specified in table 8.8.3.3.3.1-3.
Table 8.8.3.3.3.1-2: Data structures supported by the GET Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
n/a |
Table 8.8.3.3.3.1-3: Data structures supported by the GET Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
ACTStatusSubsc |
M |
1 |
200 OK |
Successful case. The requested Individual ACT Status Subscription resource is returned. |
|
n/a |
307 Temporary Redirect |
Temporary redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative EES. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [6]. |
||
|
n/a |
308 Permanent Redirect |
Permanent redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative EES. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [6]. |
||
|
NOTE: The manadatory HTTP error status code for the HTTP GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [6] also apply. |
||||
Table 8.8.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 EES. |
Table 8.8.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 EES. |
8.8.3.3.4 Resource Custom Operations
There are no resource custom operations defined for this resource in this release of the specification.
8.8.4 Custom Operations without associated resources
8.8.4.1 Overview
The structure of the custom operation URIs of the Eees_EELManagedACR API is shown in Figure 8.8.4.1-1.
Figure 8.8.4.1-1: Custom operation URI structure of the Eees_EELManagedACR API
Table 8.8.4.1-1 provides an overview of the custom operations and applicable HTTP methods defined for the Eees_EELManagedACR API.
Table 8.8.4.1-1: Custom operations without associated resources
|
Operation name |
Custom operation URI |
Mapped HTTP method |
Description |
|
RequestEELManagedACR |
/request-eelacr |
POST |
Enables a service consumer (i.e. S-EAS) to request the EES (i.e. S-EES) to handle all the operations of an ACR. |
8.8.4.2 Operation: RequestEELManagedACR
8.8.4.2.1 Description
The custom operation enables a service consumer (i.e. S-EAS) to request the EES (i.e. S-EES) to handle all the operations of an ACR.
8.8.4.2.2 Operation Definition
This operation shall support the request data structures and the response data structures and response codes specified in tables 8.8.4.2.2-1 and 8.8.4.2.2-2.
Table 8.8.4.2.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
EELACRReq |
M |
1 |
Parameters to request the EES (i.e. S-EES) to handle all the operations of an ACR. |
Table 8.8.4.2.2-2: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
EELACRResp |
M |
1 |
200 OK |
The requested EEL Managed ACR initiation was successfully received and processed. The response body contains the feedback of the EES. |
|
n/a |
307 Temporary Redirect |
Temporary redirection. The response shall include a Location header field containing an alternative target URI located in an alternative EES. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [6]. |
||
|
n/a |
308 Permanent Redirect |
Permanent redirection. The response shall include a Location header field containing an alternative target URI located in an alternative EES. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [6] |
||
|
NOTE: The manadatory HTTP error status code for the HTTP POST method listed in Table 5.2.6-1 of 3GPP TS 29.122 [6] also apply. |
||||
Table 8.8.4.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 target URI located in an alternative EES. |
Table 8.8.4.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 target URI located in an alternative EES. |
8.8.5 Notifications
8.8.5.1 General
Notifications shall comply to clause 5.2.5 of 3GPP TS 29.122 [6].
Table 8.8.5.1-1: Notifications overview
|
Notification |
Callback URI |
HTTP method or custom operation |
Description (service operation) |
|
ACT Status Notification |
{notificationUri}/act-status |
act-status (POST) |
This service operation enables an EES to notify a previously subscribed a service consumer (i.e. EAS) on ACT status information. |
8.8.5.2 ACT Status Notification
8.8.5.2.1 Description
The ACT Status Notification is used by an EES to notify a previously subscribed service consumer (i.e. EAS) on ACT status information.
8.8.5.2.2 Target URI
The Callback URI "{notificationUri}/act-status" shall be used with the callback URI variables defined in table 8.8.5.2.2-1.
Table 8.8.5.2.2-1: Callback URI variables
|
Name |
Data type |
Definition |
|
notificationUri |
Uri |
String formatted as a URI containing the Callback URI. |
8.8.5.2.3 Standard Methods
8.8.5.2.3.1 POST
This method shall support the request data structures specified in table 8.8.5.2.3.1-1 and the response data structures and response codes specified in table 8.8.5.2.3.1-2.
Table 8.8.5.2.3.1-1: Data structures supported by the POST Request Body
|
Data type |
P |
Cardinality |
Description |
|
ACTStatusNotif |
M |
1 |
Represents an ACT status notification. |
Table 8.8.5.2.3.1-2: Data structures supported by the POST Response Body
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
n/a |
204 No Content |
Successful case. The ACT status notification is successfully received and acknowledged. |
||
|
n/a |
307 Temporary Redirect |
Temporary redirection. The response shall include a Location header field containing an alternative URI representing the end point of an alternative EAS where the notification should be sent. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [6]. |
||
|
n/a |
308 Permanent Redirect |
Permanent redirection. The response shall include a Location header field containing an alternative URI representing the end point of an alternative EAS where the notification should be sent. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [6]. |
||
|
NOTE: The mandatory HTTP error status codes for the POST method listed in Table 5.2.6-1 of 3GPP TS 29.122 [6] also apply. |
||||
Table 8.8.5.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 representing the end point of an alternative EAS towards which the notification should be redirected. |
Table 8.8.5.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 representing the end point of an alternative EAS towards which the notification should be redirected. |
8.8.6 Data Model
8.8.6.1 General
This clause specifies the application data model supported by the API.
Table 8.8.6.1-1 specifies the data types defined for the Eees_EELManagedACR API.
Table 8.8.6.1-1: Eees_EELManagedACR API specific Data Types
|
Data type |
Clause defined |
Description |
Applicability |
|
EELACRReq |
8.8.6.2.2 |
Represents the parameters to request the EES (e.g. S-EES) to handle all the operations of an ACR. |
|
|
EELACRResp |
8.8.6.2.3 |
Represents the feedback of the EES on EEL Managed ACR request. |
|
|
ACTStatusSubsc |
8.8.6.2.4 |
Represents the parameters to request the creation of a subscription to ACT status reporting. |
|
|
ACTStatusNotif |
8.8.6.2.5 |
Represents an ACT status notification. |
Table 8.8.6.1-2 specifies data types re-used by the Eees_EELManagedACR API from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the Eees_EELManagedACR API.
Table 8.8.6.1-2: Eees_EELManagedACR API re-used Data Types
|
Data type |
Reference |
Comments |
Applicability |
|
ACTResult |
Clause 8.11.6.3.3 |
Represents the result of ACT. |
|
|
EasCharacteristics |
3GPP TS 24.558 [14] |
Represents the EAS characteristics. |
|
|
Gpsi |
3GPP TS 29.571 [8] |
Represents the identifier of a UE. |
|
|
SupportedFeatures |
3GPP TS 29.571 [8] |
Used to negotiate the applicability of the optional features. |
|
|
Uri |
3GPP TS 29.122 [6] |
Represents a URI. |
8.8.6.2 Structured data types
8.8.6.2.1 Introduction
This clause defines the structures to be used in resource representations.
8.8.6.2.2 Type: EELACRReq
Table 8.8.6.2.2-1: Definition of type EELACRReq
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
ueId |
Gpsi |
M |
1 |
Contains the UE identifier in the form of a GPSI. |
|
|
easCharacs |
array(EasCharacteristics) |
M |
1 |
Contains a set of EAS characteristics to be used to determine the required EASs. |
|
|
appCtxtStoreAddr |
Uri |
O |
0..1 |
Contains the URI via which the Application Context can be accessed for ACT. |
|
|
suppFeat |
SupportedFeatures |
C |
0..1 |
Contains the list of supported features among the ones defined in clause 8.8.8. This parameter shall be provided if at least one feature is supported by the EAS. |
8.8.6.2.3 Type: EELACRResp
Table 8.8.6.2.3-1: Definition of type EELACRResp
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
appCtxtStoreAddr |
Uri |
C |
0..1 |
Contains the URI via which the Application Context can be accessed for ACT. This attribute shall be included if it was not received from the EAS in the related EEL Managed ACR request. |
|
|
suppFeat |
SupportedFeatures |
C |
0..1 |
Indicates the list of negotiated supported features. This parameter shall be provided by the EES in the response to a request in which the EAS provided the list of features that it supports. |
8.8.6.2.4 Type: ACTStatusSubsc
Table 8.8.6.2.4-1: Definition of type ACTStatusSubsc
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
easId |
string |
M |
1 |
Contains the application identifier of the EAS, e.g. URI, FQDN. |
|
|
notificationUri |
Uri |
M |
1 |
Contains the URI via which the EAS desires to receive ACT status notifications. |
|
|
suppFeat |
SupportedFeatures |
C |
0..1 |
Contains the list of supported features among the ones defined in clause 8.8.8. This parameter shall be provided if at least one feature is supported by the EAS. |
8.8.6.2.5 Type: ACTStatusNotif
Table 8.8.6.2.5-1: Definition of type ACTStatusNotif
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
subscriptionId |
string |
M |
1 |
Subscription identifier. |
|
|
actStatus |
ACTResult |
M |
1 |
Contains the reported ACT status. |
8.8.6.3 Simple data types and enumerations
8.8.6.3.1 Introduction
This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses.
8.8.6.3.2 Simple data types
The simple data types defined in table 8.8.6.3.2-1 shall be supported.
Table 8.8.6.3.2-1: Simple data types
|
Type Name |
Type Definition |
Description |
Applicability |
8.8.6.4 Data types describing alternative data types or combinations of data types
There are no data types describing alternative data types or combinations of data types defined for this API in this release of the specification.
8.8.6.5 Binary data
8.8.6.5.1 Binary Data Types
Table 8.8.6.5.1-1: Binary Data Types
|
Name |
Clause defined |
Content type |
8.8.7 Error Handling
8.8.7.1 General
For the Eees_EELManagedACR API, HTTP error responses shall be supported as specified in clause 5.2.6 of 3GPP TS 29.122 [6]. Protocol errors and application errors specified in clause 5.2.6 of 3GPP TS 29.122 [6] shall be supported for the HTTP status codes specified in table 5.2.6-1 of 3GPP TS 29.122 [6].
In addition, the requirements in the following clauses are applicable for the Eees_EELManagedACR API.
8.8.7.2 Protocol Errors
No specific protocol errors for the Eees_EELManagedACR API are specified.
8.8.7.3 Application Errors
The application errors defined for the Eees_EELManagedACR API are listed in Table 8.8.7.3-1.
Table 8.8.7.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
8.8.8 Feature negotiation
The optional features in table 8.8.8-1 are defined for the Eees_EELManagedACR API. They shall be negotiated using the extensibility mechanism defined in clause 5.2.7 of 3GPP TS 29.122 [6].
Table 8.8.8-1: Supported Features
|
Feature number |
Feature Name |
Description |