5.21 EASDeployment API
29.5223GPP5G SystemNetwork Exposure Function Northbound APIsRelease 18Stage 3TS
5.21.1 Resources
5.21.1.1 Overview
All resource URIs of this API should have the following root:
{apiRoot}/3gpp-eas-deployment/v1
"apiRoot" is set as described in clause 5.2.4 in 3GPP TS 29.122 [4]. "apiName" shall be set to "3gpp-eas-deployment" 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.21.1.1-1 and the resources and HTTP methods used for AF provisioned EAS Deployment information management in the northbound EASDeployment API.
Figure 5.21.1.1-1: Resource URI structure of the northbound EASDeployment API
Table 5.21.1.1-1 provides an overview of the resources and HTTP methods applicable for the northbound EASDeployment API.
Table 5.21.1.1-1: Resources and methods overview
|
Resource name |
Resource URI |
HTTP method |
Description |
|
EAS Deployment Information |
/{afId}/eas-deployment-info |
GET |
Read all EAS Deployment information for a given AF. |
|
POST |
Create a new Individual EAS Deployment information resource. |
||
|
Individual EAS Deployment Information |
/{afId}/eas-deployment-info/{easDeployInfoId} |
GET |
Reads an active Individual EAS Deployment Information resource. |
|
PUT |
Update an existing Individual EAS Deployment Information resource. |
||
|
DELETE |
Deletes an existing Individual EAS Deployment Information resource. |
5.21.1.2 Resource: EAS Deployment Information
5.21.1.2.1 Introduction
This resource allows an AF to request the creation of a new Individual EAS Deployment Information resource.
5.21.1.2.2 Resource Definition
Resource URI: {apiRoot}/3gpp-eas-deployment/v1/{afId}/eas-deployment-info
This resource shall support the resource URI variables defined in table 5.21.1.2.2-1.
Table 5.21.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.21.1.2.3 Resource Methods
5.21.1.2.3.1 General
The following clauses specify the resource methods supported by the resource as described in clause 5.21.1.2.2.
5.21.1.2.3.2 GET
The GET method allows to read all active EAS Deployment information 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.21.1.2.3.2-1.
Table 5.21.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.21.1.2.3.2-2, the response data structures and response codes specified in table 5.21.1.2.3.2-3, and the location headers specified in table 5.21.1.2.3.2-4 and table 5.21.1.2.3.2-5.
Table 5.21.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.21.1.2.3.2-3: Data structures supported by the GET Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
array(EasDeployInfo) |
M |
0..N |
200 OK |
The configuration information for the AF in the request URI are returned. |
|
N/A |
307 Temporary Redirect |
Temporary redirection, during EAS deployment information 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 EAS deployment information 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.21.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.21.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.21.1.2.3.3 POST
The POST method creates a new resource of Individual EAS Deployment Information 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.21.1.2.3.3-1, the response data structures and response codes specified in table 5.21.1.2.3.3-2, and the Location Headers specified in table 5.21.1.2.3.3-3.
Table 5.21.1.2.3.3-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
EasDeployInfo |
M |
1 |
EAS Deployment Information, indicates how edge services are deployed in each Local DN. |
Table 5.21.1.2.3.3-2: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
EasDeployInfo |
M |
1 |
201 Created |
The Individual EAS Deployment Information resource 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.21.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-eas-deployment/v1/{afId}/eas-deployment-info/{easDeployInfoId} |
5.21.1.3 Resource: Individual EAS Deployment Information
5.21.1.3.1 Introduction
This resource allows an AF to read, update or delete an existing Individual EAS Deployment Information.
5.21.1.3.2 Resource Definition
Resource URI: {apiRoot}/3gpp-eas-deployment/v1/{afId}/eas-deployment-info/{easDeployInfoId}
This resource shall support the resource URI variables defined in table 5.21.1.3.2-1.
Table 5.21.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. |
|
easDeployInfoId |
string |
Identifier of the EAS Deployment Information formatted according to IETF RFC 3986 [44]. |
5.21.1.3.3 Resource Methods
5.21.1.3.3.1 General
The following clauses specify the resource methods supported by the resource as described in clause 5.21.1.3.2.
5.21.1.3.3.2 GET
The GET method allows to read the existing EAS Deployment Information for a given AF and a given EAS Deployment Information 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.21.1.3.3.2-1.
Table 5.21.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.21.1.3.3.2-2, the response data structures and response codes specified in table 5.21.1.3.3.2-3, and the Location Headers specified in table 5.21.1.3.3.2-4 and table 5.21.1.3.3.2-5.
Table 5.21.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.21.1.3.3.2-3: Data structures supported by the GET Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
EasDeployInfo |
M |
1 |
200 OK |
Successful case. The exposure information of an existing Individual EAS Deployment Information in the request URI is returned. |
|
N/A |
307 Temporary Redirect |
Temporary redirection, during the EAS Deployment Information 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 the EAS Deployment Information 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.21.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.21.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.21.1.3.3.3 PUT
The PUT method is used to modify an existing Individual EAS Deployment Information resource. The AF shall initiate the HTTP PUT request message and the NEF shall respond to the message.
This method shall support the URI query parameters specified in table 5.21.1.3.3.3-1.
Table 5.21.1.3.3.3-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.21.1.3.3.3-2, the response data structures and response codes specified in table 5.21.1.3.3.3-3, and the Location Headers specified in table 5.21.1.3.3.3-4 and table 5.21.1.3.3.3-5.
Table 5.21.1.3.3.3-2: Data structures supported by the PUT Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
EasDeployInfo |
M |
1 |
Modify the Individual EAS Deployment Information resource. |
Table 5.21.1.3.3.3-3: Data structures supported by the PUT Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
EasDeployInfo |
M |
1 |
200 OK |
Successful case. The exposure information of the updated EAS Deployment Information. |
|
N/A |
204 No Content |
The EAS Deployment change was updated successfully. |
||
|
N/A |
307 Temporary Redirect |
Temporary redirection, during the EAS Deployment Information 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 the EAS Deployment Information 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.21.1.3.3.3-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.21.1.3.3.3-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.21.1.3.3.4 DELETE
The DELETE method deletes an existing Individual EAS Deployment Information resource. 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.21.1.3.3.4-1.
Table 5.21.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.21.1.3.3.4-2, the response data structures and response codes specified in table 5.21.1.3.3.4-3, and the Location Headers specified in table 5.21.1.3.3.4-4 and table 5.21.1.3.3.4-5.
Table 5.21.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.21.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 Individual EAS Deployment Information resource was terminated successfully. |
||
|
N/A |
307 Temporary Redirect |
Temporary redirection, during the 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 the 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.21.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.21.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.21.2 Custom Operations without associated resources
5.21.2.1 Overview
The structure of the custom operation URIs of the Nnef_EASDeployment service is shown in Figure 5.21.2.1-1.
Figure 5.21.2.1-1: Custom operation URI structure of the Nnef_EASDeployment API
Table 5.21.2.1-1 provides an overview of the custom operations and applicable HTTP methods.
Table 5.21.2.1-1: Custom operations without associated resources
|
Custom operation URI |
Mapped HTTP method |
Description |
|
{apiRoot}/3gpp-eas-deployment/<apiVersion>/remove-edis |
POST |
Request the NEF to delete EAS Deployment Information based on given attributes. |
5.21.2.2 Operation: remove-edis
5.21.2.2.1 Description
The operation is used by the NF service consumer to delete EAS Deployment Information based on given attributes.
5.21.2.2.2 Operation Definition
This operation shall support the request data structures shown in Table 5.21.2.2.2-1 and the response data structures and error codes specified in Table 5.21.2.2.2-2.
Table 5.21.2.2.2-1: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
EdiDeleteCriteria |
M |
1 |
Information about the criteria to be used for EAS Deployment Information deletion. |
Table 5.21.2.2.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 |
Successful request to remove EAS Deployment Information based on given criteria. |
||
|
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. |
||||
5.21.3 Notifications
None.
5.21.4 Data Model
5.21.4.1 General
This clause specifies the application data model supported by the EASDeployment API. Table 5.21.4.1-1 specifies the data types defined for the EASDeployment API.
Table 5.21.4.1-1: EASDeployment API specific Data Types
|
Data type |
Clause defined |
Description |
Applicability |
|
EasDeployInfo |
5.21.4.3.2 |
EAS Deployment Information, indicates how edge services are deployed in each Local DN. |
|
|
EdiDeleteCriteria |
5.21.4.3.5 |
Contains criteria for deleting EAS Deployment Information. |
|
|
DnaiInformation |
5.21.4.3.3 |
list of DNS server identifier and/or IP address(s) of the EAS in the local DN for the DNAI. |
|
|
DnsServerIdentifier |
5.21.4.3.4 |
DNS server identifier (consisting of IP address and port). |
5.21.4.2 Reused data types
The data types reused by the EASDeployment API from other specifications are listed in table 5.21.4.2-1.
Table 5.21.4.2-1: Re-used Data Types
|
Data type |
Reference |
Comments |
|
AfId |
5.14.5.4.2 |
Represents an AF identifier. |
|
Dnai |
3GPP TS 29.571 [8] |
Identifies a DNAI. |
|
Dnn |
3GPP TS 29.571 [8] |
Identifies a DNN. |
|
DnnSnssaiInformation |
5.18.3.3.5 |
Contains DNN and S-NSSAI information. |
|
ExternalGroupId |
3GPP TS 29.122 [4] |
External Group Identifier for a user group. |
|
FqdnPatternMatchingRule |
3GPP TS 29.571 [8] |
Identifies the FQDN pattern matching rule. |
|
IpAddr |
3GPP TS 29.571 [8] |
IP Address. |
|
Snssai |
3GPP TS 29.571 [8] |
Identifies the S-NSSAI. |
|
Uinteger |
3GPP TS 29.571 [8] |
Unsigned integer. |
|
Link |
3GPP TS 29.122 [4] |
Identifies a referenced resource. |
5.21.4.3 Structured data types
5.21.4.3.1 Introduction
This clause defines the structured data types to be used in resource representations.
5.21.4.3.2 Type: EasDeployInfo
Table 5.21.4.3.2-1: Definition of type EasDeployInfo
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
self |
Link |
C |
0..1 |
Identifies the individual EAS Deployment information resource. Shall be present in the HTTP GET response when reading all the configurations for an AF. |
|
|
afServiceId |
string |
O |
0..1 |
Identifies a service on behalf of which the AF is issuing the request. |
|
|
fqdnPatternList |
array(FqdnPatternMatchingRule) |
M |
1..N |
Supported FQDN pattern(s) for application(s) deployed in the Local part of the DN where each FQDN pattern is described by a FQDN Pattern Matching Rule. |
|
|
appId |
string |
O |
0..1 |
Identifies the application for which the EAS Deployment Information corresponds to. |
|
|
dnn |
Dnn |
O |
0..1 |
DNN for the EAS Deployment Information. |
|
|
snssai |
Snssai |
O |
0..1 |
S-NSSAI for the EAS Deployment Information. |
|
|
exterGroupId |
ExternalGroupId |
O |
0..1 |
External Group ID for the EAS Deployment Information. |
|
|
dnaiInfos |
map(DnaiInformation) |
O |
1..N |
list of DNS server identifier (consisting of IP address and port) and/or IP address(s) of the EAS in the local DN for each DNAI. The key of map is the DNAI. |
5.21.4.3.3 Type: DnaiInformation
Table 5.21.4.3.3-1: Definition of type DnaiInformation
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
dnai |
Dnai |
M |
1 |
Identifer the DNAI. |
|
|
dnsServIds |
array(DnsServerIdentifier) |
C |
1..N |
list of DNS server identifier (consisting of IP address and port) for each DNAI. |
|
|
easIpAddrs |
array(IpAddr) |
C |
1..N |
IP address(s) of the EASs in the local DN for each DNAI. |
|
|
NOTE: At least one of the "dnsServIds" or "easIpAddrs" attribute shall be provided. |
|||||
5.21.4.3.4 Type: DnsServerIdentifier
Table 5.21.4.3.4-1: Definition of type DnsServerIdentifier
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
dnsServIpAddr |
IpAddr |
M |
1 |
DNS server IP address. |
|
|
portNumber |
Uinteger |
M |
1 |
DNS port number. |
5.21.4.3.5 Type: EdiDeleteCriteria
Table 5.21.4.3.5-1: Definition of type EdiDeleteCriteria
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
afId |
AfId |
C |
0..1 |
AF identifier to be used as deletion criterion. (NOTE) |
|
|
dnnSnssai |
DnnSnssaiInformation |
C |
0..1 |
DNN and S-NSSAI information to be used as deletion criterion. (NOTE) |
|
|
NOTE: At least one of those attributes shall be provided. |
|||||
5.21.4.4 Simple data types and enumerations
5.21.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.21.4.4.2 Simple data types
The simple data types defined in table 5.21.4.4.2-1 shall be supported.
Table 5.21.4.4.2-1: Simple data types
|
Type Name |
Type Definition |
Description |
Applicability |
5.21.5 Used Features
The table below defines the features applicable to the EASDeployment API. Those features are negotiated as described in clause 5.2.7 of 3GPP TS 29.122 [4].
Table 5.21.5-1: Features used by EASDeployment API
|
Feature number |
Feature Name |
Description |
5.21.6 Error handling
5.21.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.21.6.2 Protocol Errors
In this Release of the specification, there are no additional protocol errors applicable for the EASDeployment API.
5.21.6.3 Application Errors
The application errors defined for EASDeployment API are listed in table 5.21.6.3-1.
Table 5.21.6.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
Applicability |