5.11 PfdManagement API
29.1223GPPRelease 18T8 reference point for Northbound APIsTS
5.11.1 Overview
The PfdManagement API allows the SCS/AS to manage the PFDs via the SCEF. The PfdManagement API defines a set of data models, resources and the related procedures for the creation and management of the PFD management request. The corresponding JSON schema for the representation of the resources and operations defined by the PfdManagement API is provided in its complete form in Annex A.11.
5.11.2 Data model
5.11.2.1 Resource data types
5.11.2.1.1 Introduction
This clause defines data structures to be used in resource representations.
Table 5.11.2.1.1-1 specifies data types re-used by the PfdManagement API from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the PfdManagement API.
Table 5.11.2.1.1-1: PfdManagement API re-used Data Types
Data type |
Reference |
Comments |
SupportedFeatures |
3GPP TS 29.571 [45] |
Used to negotiate the applicability of the optional features defined in table 5.11.4-1. |
Dnai |
3GPP TS 29.571 [45] |
DNAI |
Table 5.11.2.1.1-2 specifies the data types defined for the PfdManagement API.
Table 5.11.2.1.1-2: PfdManagement API specific Data Types
Data type |
Clause defined |
Description |
Applicability |
DomainNameProtocol |
5.11.2.2.4 |
Indicates the additional protocol and protocol field for domain names to be matched. |
DomainNameProtocol |
FailureCode |
5.11.2.2.3 |
Represents the failure reason of the PFD management. |
|
Pfd |
5.11.2.1.4 |
Represents a PFD for an external Application Identifier. |
|
PfdData |
5.11.2.1.3 |
Represents a PFD request to add, update or remove PFD(s) for one external application identifier. |
|
PfdManagement |
5.11.2.1.2 |
Represents a PFD management resource for a PFD management request. |
|
PfdManagementPatch |
5.11.2.1.7 |
Represents the parameters to request the modification of a PFD management transaction resource. |
PatchUpdate |
PfdReport |
5.11.2.1.5 |
Represents a PFD report indicating the external application identifier(s) which PFD(s) are not added or modified successfully and the corresponding failure cause(s). |
|
UserPlaneLocationArea |
5.11.2.1.6 |
Represents location area(s) of the user plane functions which are unable to enforce the provisioned PFD(s) successfully. |
5.11.2.1.2 Type: PfdManagement
This type represents a PFD management resource for a PFD management request.
Table 5.11.2.1.2-1: Definition of type PfdManagement
Attribute name |
Data type |
Cardinality |
Description |
Applicability (NOTE 1) |
self |
Link |
0..1 |
Link to the resource "Individual PFD Management Transaction". This parameter shall be supplied by the SCEF in HTTP responses. |
|
supportedFeatures |
SupportedFeatures |
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. |
|
pfdDatas |
map(PfdData) |
1..N |
Each element uniquely identifies the PFDs for an external application identifier. Each element is identified in the map via an external application identifier as key. The response shall include successfully provisioned PFD data of application(s). |
|
pfdReports |
map(PfdReport) |
0..N |
Supplied by the SCEF and contains the external application identifiers for which PFD(s) are not added or modified successfully. The failure reason is also included. Each element provides the related information for one or more external application identifier(s) and is identified in the map via the failure identifier as key. (NOTE 2) |
|
notificationDestination |
Link |
0..1 |
A URI indicating the notification destination for T8 notifications. |
PfdMgmtNotification |
requestTestNotification |
boolean |
0..1 |
Set to true by the SCS/AS to request the SCEF to send a test notification as defined in clause 5.2.5.3. Set to false or omitted otherwise. |
Notification_test_event |
websockNotifConfig |
WebsockNotifConfig |
0..1 |
Configuration parameters to set up notification delivery over Websocket protocol as defined in clause 5.2.5.4. |
Notification_websocket |
NOTE 1: Properties marked with a feature as defined in clause 5.11.4 are applicable as described in clause 5.2.7. If no feature are indicated, the related property applies for all the features. NOTE 2: The failure identifier is a string encoded map key. |
5.11.2.1.3 Type: PfdData
This type represents a PFD request to add, update or remove PFD(s) for one external application identifier provided by the SCS/AS to the SCEF via T8 interface.
Table 5.11.2.1.3-1: Definition of type PfdData
Attribute name |
Data type |
Cardinality |
Description |
Applicability (NOTE 1) |
externalAppId |
string |
1 |
Each element uniquely external application identifier (NOTE 2) |
|
self |
Link |
0..1 |
Link to the resource "Individual Application PFD Management". This parameter shall be supplied by the SCEF in HTTP responses. |
|
pfds |
map(Pfd) |
1..N |
Contains the PFDs of the external application identifier. Each PFD is identified in the map via a key containing the PFD identifier. (NOTE 3) |
|
allowedDelay |
DurationSecRm |
0..1 |
Indicates that the list of PFDs in this request should be deployed within the time interval indicated by the Allowed Delay |
|
cachingTime |
DurationSecRo |
0..1 |
SCEF supplied property, inclusion of this property means the allowed delayed cannot be satisfied, i.e. it is smaller than the caching time, but the PFD data is still stored. |
|
NOTE 1: Properties marked with a feature as defined in clause 5.11.4 are applicable as described in clause 5.2.7. If no features are indicated, the related property applies for all the features. NOTE 2: An externalAppId can only belong to one "individual PFD Management Transaction" resource. NOTE 3: When multiple PFDs are associated with application identifier, the application is detected when any of the PFDs associated with the application identifier is matched. |
5.11.2.1.4 Type: Pfd
This data type represents a PFD for an external Application Identifier.
Table 5.11.2.1.4-1: Definition of type Pfd
Attribute name |
Data type |
Cardinality |
Description |
Applicability (NOTE 1) |
pfdId |
string |
1 |
Identifies a PFD of an application identifier. |
|
flowDescriptions |
array(string) |
0..N |
Represents a 3-tuple with protocol, server ip and server port for UL/DL application traffic. The content of the string has the same encoding as the IPFilterRule AVP value as defined in IETF RFC 6733 [46]. (NOTE 2) |
|
urls |
array(string) |
0..N |
Indicates a URL or a regular expression which is used to match the significant parts of the URL. (NOTE 2) |
|
domainNames |
array(string) |
0..N |
Indicates an FQDN or a regular expression as a domain name matching criteria. (NOTE 2) |
|
dnProtocol |
DomainNameProtocol |
0..1 |
Indicates the additional protocol and protocol field for domain names to be matched, it may only be provided when domainNames attribute is present. |
DomainNameProtocol |
NOTE 1: Properties marked with a feature as defined in clause 5.11.4 are applicable as described in clause 5.2.7. If no features are indicated, the related property applies for all the features. NOTE 2: At least one of the properties "flowDescriptions", "urls" or "domainNames" shall be included. If a PFD contains multiple filter types, the PFD is only matched when every filter type contained in the PFD has a matching value. |
5.11.2.1.5 Type: PfdReport
This type represents a PFD report to indicate the external application identifier(s) which PFD(s) are not added or modified successfully and corresponding failure reason.
Table 5.11.2.1.5-1: Definition of type PfdReport
Attribute name |
Data type |
Cardinality |
Description |
Applicability (NOTE) |
externalAppIds |
array(string) |
1..N |
Identifies the external application identifier(s) which PFD(s) are not added or modified successfully |
|
failureCode |
FailureCode |
1 |
Identifies the failure reason |
|
cachingTime |
DurationSec |
0..1 |
It shall be included when the allowed delayed cannot be satisfied, i.e. it is smaller than the caching time configured in fetching PFD. |
|
locationArea |
UserPlaneLocationArea |
0..1 |
Identifies a location area of the user plane(s) which are unable to enforce the PFD(s). |
|
NOTE: Properties marked with a feature as defined in clause 5.11.4 are applicable as described in clause 5.2.7. If no feature are indicated, the related property applies for all the features. |
5.11.2.1.6 Type: UserPlaneLocationArea
This data type represents location area(s) of the user plane which is unable to enforce the provisioned PFD(s) successfully. It is sent from the SCEF to the SCS/AS.
Table 5.11.2.1.6-1: Definition of the UserPlaneLocationArea data Type
Attribute name |
Data type |
Cardinality |
Description |
Applicability (NOTE) |
locationArea |
LocationArea |
0..1 |
Identifies the network area information served by the user planes functions which are unable to enforce the provisioned PFD(s) successfully. It can be either a list of cell IDs, or a list of Tracking Areas, or civic addresses, or a geographic area, or a combination of any of the above. |
|
locationArea5G |
LocationArea5G |
0..1 |
Identifies the network area information served by the user planes functions which are unable to enforce the provisioned PFD(s) successfully. It can be either a list of E-UTRA cell IDs, or a list of NR cell ID, or a list of Tracking Areas, or civic addresses, or a geographic area, or a combination of any of the above. |
FailureLocation_5G |
dnais |
array(DNAI) |
0..N |
Identifies a list of DNAI supported by the user plane functions which are unable to enforce the provisioned PFD(s) successfully. |
FailureLocation_5G |
5.11.2.1.7 Type: PfdManagementPatch
This type represents the parameters to request the modification of a PFD management transaction resource.
Table 5.11.2.1.7-1: Definition of type PfdManagementPatch
Attribute name |
Data type |
Cardinality |
Description |
Applicability (NOTE 1) |
pfdDatas |
map(PfdData) |
1..N |
Each element uniquely identifies the PFDs for an external application identifier. Each element is identified in the map via an external application identifier as the key. |
|
notificationDestination |
Link |
0..1 |
A URI indicating the notification destination for T8 notifications. |
|
NOTE 1: Properties marked with a feature as defined in clause 5.11.4 are applicable as described in clause 5.2.7. If no feature are indicated, the related property applies for all the features. |
5.11.2.2 Referenced simple data types and enumerations
5.11.2.2.1 Introduction
This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses. In addition, data types and enumerations defined in clause 5.2.1 can be referenced.
5.11.2.2.2 Simple data types
The simple data types defined in table 5.11.2.2.2-1 shall be supported.
Table 5.11.2.2.2-1: Simple data types
Type name |
Description |
5.11.2.2.3 Enumeration: FailureCode
The enumeration FailureCode represents the failure reason of the PFD management.
Table 5.11.2.2.3-1: Enumeration FailureCode
Enumeration value |
Description |
Applicability (NOTE) |
MALFUNCTION |
This value indicates that something functions wrongly in PFD provisioning or the PFD provisioning does not function at all. |
|
RESOURCE_LIMITATION |
This value indicates there is resource limitation for PFD storage. |
|
SHORT_DELAY |
This value indicates that the allowed delay is too short and PFD(s) are not stored. |
|
APP_ID_DUPLICATED |
The received external application identifier(s) are already provisioned. |
|
PARTIAL_FAILURE |
The PFD(s) are not provisioned to all PCEFs/TDFs/SMFs. |
PfdMgmtNotification |
OTHER_REASON |
Other reason unspecified. |
|
NOTE: Properties marked with a feature as defined in clause 5.11.4 are applicable as described in clause 5.2.7. If no feature are indicated, the related property applies for all the features. |
5.11.2.2.4 Enumeration: DomainNameProtocol
Table 5.14.2.2.4-1: Enumeration DomainNameProtocol
Enumeration value |
Description |
Applicability (NOTE) |
DNS_QNAME |
Identifies the DNS protocol and the question name in DNS query. |
|
TLS_SNI |
Identifies the Server Name Indication in TLS ClientHello message. |
|
TLS_SAN |
Identifies the Subject Alternative Name in TLS ServerCertificate message. |
|
TLS_SCN |
Identifies the Subject Common Name in TLS ServerCertificate message. |
|
NOTE: Properties marked with a feature as defined in clause 5.10.4 are applicable as described in clause 5.2.7. If no features are indicated, the related property applies for all the features. |
5.11.3 Resource structure
5.11.3.1 General
All resource URIs of this API should have the following root:
{apiRoot}/3gpp-pfd-management/v1
"apiRoot" is set as described in clause 5.2.4. "apiName" shall be set to "3gpp-pfd-management" and "apiVersion" shall be set to "v1" for the version defined in the present document. All resource URIs in the clauses below are defined relative to the above root URI.
The following resources and HTTP methods are supported for this API:
Table 5.11.3.1-1: Resources and methods overview
Resource name |
Resource URI |
HTTP method |
Meaning |
PFD Management Transactions |
/{scsAsId}/transactions |
GET |
Read all or queried PFDs for a given SCS/AS |
POST |
Create PFDs for a given SCS/AS and one or more external Application Identifier(s) |
||
Individual PFD Management Transaction |
/{scsAsId}/transactions/{transactionId} |
GET |
Read all PFDs for a given SCS/AS and a transaction for one or more external Application Identifier(s) |
PUT |
Update PFD(s) for a given SCS/AS and a transaction for one or more external Application Identifier(s) |
||
PATCH |
Modify PFD(s) for a given SCS/AS and a transaction for one or more external Application Identifier(s). |
||
DELETE |
Delete PFDs for a given SCS/AS and a transaction for one or more external Application Identifier(s) |
||
Individual Application PFD Management |
/{scsAsId}/transactions/{transactionId}/applications/{appId} (NOTE) |
PUT |
Update PFDs at individual application level |
PATCH |
Update PFDs at individual application level |
||
GET |
Read PFDs at individual application level |
||
DELETE |
Delete PFDs at individual application level |
||
NOTE: The appId as the resource identifier is not necessarily identical as the external application identifier received from the SCS/AS. |
5.11.3.2 Resource: PFD Management Transactions
5.11.3.2.1 Introduction
This resource allows an SCS/AS to read all PFDs for a given SCS/AS or create PFDs for a given SCS/AS with one or more external Application Identifier(s).
5.11.3.2.2 Resource definition
Resource URI: {apiRoot}/3gpp-pfd-management/v1/{scsAsId}/transactions
This resource shall support the resource URI variables defined in table 5.11.3.2.2-1.
Table 5.11.3.2.2-1: Resource URI variables for resource "PFD Management Transactions"
Name |
Data type |
Definition |
apiRoot |
string |
See clause 5.2.4. |
scsAsId |
string |
Identifier of the SCS/AS. |
5.11.3.2.3 Resource methods
5.11.3.2.3.1 GET
The GET method allows to read all or queried active PFDs for a given SCS/AS. It is initiated by the SCS/AS and answered by the SCEF.
This method shall support the URI query parameters as specified in the table 5.11.3.2.3.1-0.
Table 5.11.3.2.3.1-0: URI query parameters supported by the GET method on this resource
Name |
Data type |
Cardinality |
Remarks |
Applicability |
external-app-ids |
array(string) |
0..N |
The external application identifier(s) of the requested PFD data. |
enNB |
NOTE: If multiple elements are provided in the array data structure, then each element shall be treated as a separate query parameter. |
This method shall support the request and response data structures, and response codes, as specified in the table 5.11.3.2.3.1-1.
Table 5.11.3.2.3.1-1: Data structures supported by the GET request/response by the resource
Request body |
Data type |
Cardinality |
Remarks |
|
none |
||||
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
array(PfdManagement) |
0..N |
200 OK |
All or queried transactions including the PFDs for the SCS/AS in the request URI are returned. |
|
none |
307 Temporary Redirect |
Temporary redirection, during transaction retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
none |
308 Permanent Redirect |
Permanent redirection, during transaction retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
NOTE: The mandatory HTTP error status codes for the GET method listed in table 5.2.6-1 also apply. |
Table 5.11.3.2.3.1-2: 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 SCEF. |
Table 5.11.3.2.3.1-3: 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 SCEF. |
5.11.3.2.3.2 PUT
This HTTP method is not supported for the resource.
5.11.3.2.3.3 POST
The POST method creates new PFDs resource(s) for a given SCS/AS with one or more external Application Identifier provided by the SCS/AS. It is initiated by the SCS/AS and answered by the SCEF. The SCS/AS shall provide the external Application Identifier in the message body and upon receipt of the HTTP POST message, the SCEF shall generate the resource "Individual PFD Management Transaction" and also the sub-resource(s) "Individual Application PFD Management", the SCEF shall send these resource URI in the HTTP response to the SCS/AS.
This method shall support the request and response data structures, and response codes, as specified in the table 5.11.3.2.3.3-1.
Table 5.11.3.2.3.3-1: Data structures supported by the POST request/response by the resource
Request body |
Data type |
Cardinality |
Remarks |
|
PfdManagement |
1 |
|||
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
PfdManagement |
1 |
201 Created |
The PFDs resource was created successfully. PfdReport may be included to provide detailed failure information for some applications. |
|
array(PfdReport) |
1..N |
500 Internal Server Error |
The PFDs for all applications were not created successfully. PfdReport is included with detailed information. |
|
NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 also apply. |
Table 5.11.3.2.3.3-2: 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-pfd-management/v1/{scsAsId}/transactions/{transactionId} |
5.11.3.2.3.4 PATCH
This HTTP method is not supported for the resource.
5.11.3.2.3.5 DELETE
To remove all PFDs for a given SCS/AS, the SCS/AS shall use the HTTP DELETE method on the "PFD Management Transactions" resource.
The possible response messages from the SCEF, depending on whether the DELETE request is successful or unsuccessful, are shown in table 5.11.3.2.3.5-1.
Table 5.11.3.2.3.5-1: Data structures supported by the DELETE request/response by the resource
Request body |
Data type |
Cardinality |
Remarks |
|
none |
||||
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
none |
204 No Content |
All PFDs were removed successfully. The SCEF shall not return a response payload. |
||
none |
307 Temporary Redirect |
Temporary redirection, during transaction termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
none |
308 Permanent Redirect |
Permanent redirection, during transaction termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
NOTE: The mandatory HTTP error status codes for the DELETE method listed in table 5.2.6-1 also apply. |
Table 5.11.3.2.3.5-2: 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 SCEF. |
Table 5.11.3.2.3.5-3: 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 SCEF. |
5.11.3.3 Resource: Individual PFD Management Transaction
5.11.3.3.1 Introduction
This resource allows an SCS/AS to read, or update or delete PFDs for a given SCS/AS and a transaction Id for one or more application identifier(s) at the SCEF.
5.11.3.3.2 Resource definition
Resource URI: {apiRoot}/3gpp-pfd-management/v1/{scsAsId}/transactions/{transactionId}
This resource shall support the resource URI variables defined in table 5.11.3.3.2-1.
Table 5.11.3.3.2-1: Resource URI variables for resource "Individual PFD Management Transaction"
Name |
Data type |
Definition |
apiRoot |
string |
See clause 5.2.4. |
scsAsId |
string |
Identifier of the SCS/AS. |
transactionId |
string |
Identifier of the transaction. The transactionId corresponds to the stage 2 TLTRI. |
5.11.3.3.3 Resource methods
5.11.3.3.3.1 GET
The GET method allows to read all PFDs for a given SCS/AS and a transaction Id generated by the SCEF. It is initiated by the SCS/AS and answered by the SCEF.
This method shall support request and response data structures, and response codes, as specified in the table 5.11.3.3.3.1-1.
Table 5.11.3.3.3.1-1: Data structures supported by the GET request/response by the resource
Request body |
Data type |
Cardinality |
Remarks |
|
none |
||||
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
PfdManagement |
1 |
200 OK |
The PFDs for the SCS/AS and the transaction Id for one or more application identifier(s) in the request URI are returned. |
|
none |
307 Temporary Redirect |
Temporary redirection, during transaction retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
none |
308 Permanent Redirect |
Permanent redirection, during transaction retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
NOTE: The mandatory HTTP error status codes for the GET method listed in table 5.2.6-1 also apply. |
Table 5.11.3.3.3.1-2: 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 SCEF. |
Table 5.11.3.3.3.1-3: 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 SCEF. |
5.11.3.3.3.2 PUT
The PUT method modifies the PFDs for a given SCS/AS and an existing transaction Id generated by the SCEF. It is initiated by the SCS/AS and answered by the SCEF.
This method shall support the request and response data structures, and response codes, as specified in the table 5.11.3.3.3.2-1.
Table 5.11.3.3.3.2-1: Data structures supported by the PUT request/response by the resource
Request body |
Data type |
Cardinality |
Remarks |
|
PfdManagement |
1 |
Update of PFD(s) for an existing transaction Id. |
||
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
PfdManagement |
1 |
200 OK |
The PFDs were updated successfully and a representation is returned. PfdReport may be included to provide detailed failure information for some applications. |
|
none |
204 No Content |
The PFDs were updated successfully. |
||
array(PfdReport) |
1..N |
500 Internal Server Error |
The PFDs for all applications were not updated successfully. PfdReport is included with detailed information. |
|
none |
307 Temporary Redirect |
Temporary redirection, during transaction modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
none |
308 Permanent Redirect |
Permanent redirection, during transaction modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
NOTE: The mandatory HTTP error status codes for the PUT method listed in table 5.2.6-1 also apply. |
Table 5.11.3.3.3.2-2: 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 SCEF. |
Table 5.11.3.3.3.2-3: 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 SCEF. |
5.11.3.3.3.3 PATCH
The PATCH method modifies an existing PFD Management Transaction resource. The SCS/AS shall initiate the HTTP PATCH request message and the SCEF shall respond to the message.
This method shall support the request and response data structures, and response codes, as specified in the table 5.11.3.3.3.3-1.
Table 5.11.3.3.3.3-1: Data structures supported by the PATCH request/response by the resource
Request body |
Data type |
Cardinality |
Remarks |
|
PfdManagementPatch |
1 |
Modify of PFD(s) for an existing transaction ID. |
||
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
PfdManagement |
1 |
200 OK |
The PFDs were modified successfully and a representation of the modified resource is returned. The PfdReport data structure may be included in the response to provide the detailed failure information if the modification failed for some applications. |
|
none |
204 No Content |
The PFDs were modified successfully. |
||
array(PfdReport) |
1..N |
500 Internal Server Error |
The PFDs for all applications were not modified successfully. PFD Report(s) shall be included in the response body with the detailed information. |
|
none |
307 Temporary Redirect |
Temporary redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
none |
308 Permanent Redirect |
Permanent redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
NOTE: The mandatory HTTP error status codes for the PATCH method listed in table 5.2.6-1 also apply. |
Table 5.11.3.3.3.3-2: 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 SCEF. |
Table 5.11.3.3.3.3-3: 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 SCEF. |
5.11.3.3.3.4 POST
This HTTP method is not supported for the resource.
5.11.3.3.3.5 DELETE
The DELETE method deletes the PFDs for a given SCS/AS and an transaction Id generated by the SCEF. It is initiated by the SCS/AS and answered by the SCEF.
This method shall support the URI query parameters, request and response data structures, and response codes, as specified in the table 5.11.3.3.3.5-1 and table 5.11.3.3.3.5-2.
Table 5.11.3.3.3.5-1: URI query parameters supported by the DELETE method on this resource
Name |
Data type |
Cardinality |
Remarks |
N/A |
Table 5.11.3.3.3.5-2: Data structures supported by the DELETE request/response by the resource
Request body |
Data type |
Cardinality |
Remarks |
|
none |
||||
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
None |
204 No Content |
The PFDs for an existing transaction Id were removed successfully. |
||
none |
307 Temporary Redirect |
Temporary redirection, during transaction termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
none |
308 Permanent Redirect |
Permanent redirection, during transaction termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
NOTE: The mandatory HTTP error status codes for the DELETE method listed in table 5.2.6-1 also apply. |
Table 5.11.3.3.3.5-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 SCEF. |
Table 5.11.3.3.3.5-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 SCEF. |
5.11.3.4 Resource: Individual Application PFD Management
5.11.3.4.1 Introduction
This resource allows an SCS/AS to read, update or remove the PFDs for a given SCS/AS and an external Application Identifier at the SCEF.
5.11.3.4.2 Resource definition
Resource URI: {apiRoot}/3gpp-pfd-management/v1/{scsAsId}/transactions/{transactionId}/applications/{appId}
This resource shall support the resource URI variables defined in table 5.11.3.4.2-1.
Table 5.11.3.3.4-1: Resource URI variables for resource "Individual Application PFD Management"
Name |
Data type |
Definition |
apiRoot |
string |
See clause 5.2.4. |
scsAsId |
string |
Identifier of the SCS/AS. |
transactionId |
string |
Identifier of the transaction. |
appId |
string |
External Application Identifier. |
5.11.3.4.3 Resource methods
5.11.3.4.3.1 GET
The GET method allows to read all PFDs at individual application level. It is initiated by the SCS/AS and answered by the SCEF.
This method shall support request and response data structures, and response codes, as specified in the table 5.11.3.4.3.1-1.
Table 5.11.3.4.3.1-1: Data structures supported by the GET request/response by the resource
Request body |
Data type |
Cardinality |
Remarks |
|
None |
||||
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
PfdData |
1 |
200 OK |
The PFDs at individual application level in the request URI are returned. |
|
none |
307 Temporary Redirect |
Temporary redirection, during transaction retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
none |
308 Permanent Redirect |
Permanent redirection, during transaction retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
NOTE: The mandatory HTTP error status codes for the GET method listed in table 5.2.6-1 also apply. |
Table 5.11.3.4.3.1-2: 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 SCEF. |
Table 5.11.3.4.3.1-3: 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 SCEF. |
5.11.3.4.3.2 PUT
The PUT method modifies the PFDs at individual application level. It is initiated by the SCS/AS and answered by the SCEF.
This method shall support the request and response data structures, and response codes, as specified in the table 5.11.3.4.3.2-1.
Table 5.11.3.4.3.2-1: Data structures supported by the PUT request/response by the resource
Request body |
Data type |
Cardinality |
Remarks |
|
PfdData |
1 |
Update of PFD(s) for an existing external application identifier. |
||
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
PfdData |
1 |
200 OK |
The PFDs for the existing external application identifier were updated successfully and a representation is returned. |
|
none |
204 No Content |
The PFDs for the existing external application identifier were updated successfully. |
||
PfdReport |
1 |
403 Forbidden |
The PFDs for the application were not updated successfully, applicable for error SHORT_DELAY in table 5.11.2.2.3-1. |
|
PfdReport |
1 |
409 Conflict |
The PFDs for the application were not updated successfully, applicable for error APP_ID_DUPLICATED in table 5.11.2.2.3-1. |
|
PfdReport |
1 |
500 Internal Server Error |
The PFDs for the application were not updated successfully, applicable for other errors in table 5.11.2.2.3-1. |
|
none |
307 Temporary Redirect |
Temporary redirection, during transaction modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
none |
308 Permanent Redirect |
Permanent redirection, during transaction modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
NOTE: The mandatory HTTP error status codes for the PUT method listed in table 5.2.6-1 also apply. |
Table 5.11.3.4.3.2-2: 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 SCEF. |
Table 5.11.3.4.3.2-3: 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 SCEF. |
5.11.3.4.3.3 PATCH
The PATCH method modifies the PFDs at individual application level. It is initiated by the SCS/AS and answered by the SCEF.
This method shall support the request and response data structures, and response codes, as specified in the table 5.11.3.4.3.3-1.
Table 5.11.3.4.3.3-1: Data structures supported by the PATCH request/response by the resource
Request body |
Data type |
Cardinality |
Remarks |
|
PfdData |
1 |
Update of PFD(s) for an existing external application identifier. |
||
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
PfdData |
1 |
200 OK |
The PFDs for the existing external application identifier were updated successfully and a representation is returned. |
|
none |
204 No Content |
The PFDs for the existing external application identifier were updated successfully. |
||
PfdReport |
1 |
403 Forbidden |
The PFDs for the application were not updated successfully, applicable for error SHORT_DELAY in table 5.11.2.2.3-1. |
|
PfdReport |
1 |
409 Conflict |
The PFDs for the application were not updated successfully, applicable for error APP_ID_DUPLICATED in table 5.11.2.2.3-1. |
|
PfdReport |
1 |
500 Internal Server Error |
The PFDs for the application were not updated successfully, applicable for other errors in table 5.11.2.2.3-1. |
|
none |
307 Temporary Redirect |
Temporary redirection, during transaction modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
none |
308 Permanent Redirect |
Permanent redirection, during transaction modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
NOTE: The mandatory HTTP error status codes for the PATCH method listed in table 5.2.6-1 also apply. |
Table 5.11.3.4.3.3-2: 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 SCEF. |
Table 5.11.3.4.3.3-3: 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 SCEF. |
5.11.3.4.3.4 POST
This HTTP method is not supported for the resource.
5.11.3.4.3.5 DELETE
The DELETE method deletes all the PFDs at individual application level. It is initiated by the SCS/AS and answered by the SCEF.
This method shall support the URI query parameters, request and response data structures, and response codes, as specified in the table 5.11.3.4.3.5-1 and table 5.11.3.4.3.5-2.
Table 5.11.3.4.3.5-1: URI query parameters supported by the DELETE method on this resource
Name |
Data type |
Cardinality |
Remarks |
N/A |
Table 5.11.3.4.3.5-2: Data structures supported by the DELETE request/response by the resource
Request body |
Data type |
Cardinality |
Remarks |
|
none |
||||
Response body |
Data type |
Cardinality |
Response codes |
Remarks |
none |
204 No Content |
The PFDs were removed successfully. |
||
none |
307 Temporary Redirect |
Temporary redirection, during transaction termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
none |
308 Permanent Redirect |
Permanent redirection, during transaction termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SCEF. Redirection handling is described in clause 5.2.10. |
||
NOTE: The mandatory HTTP error status codes for the DELETE method listed in table 5.2.6-1 also apply. |
Table 5.11.3.4.3.5-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 SCEF. |
Table 5.11.3.4.3.5-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 SCEF. |
5.11.3.5 Void
5.11.3A Notifications
5.11.3A.1 General
The notifications provided by the PfdManagement API are specified in this clause.
Table 5.11.3A-1: Notifications overview
Notification |
Callback URI |
HTTP method or custom operation |
Description (service operation) |
PFD Management Notification |
{notificationDestination} |
POST |
Send asynchronous PFD management result. |
5.11.3A.2 PFD Management Notification
5.11.3A.2.1 Description
The PFD Management Notification allows the SCEF to send notification about PFD management result to the SCS/AS, if the PFD provisioning fails within the allowed delay.
5.11.3A.2.2 Target URI
The Callback URI "{notificationDestination}" shall be used with the callback URI variables defined in table 5.11.3A.2.2-1.
Table 5.11.3A.2.2-1: Callback URI variables
Name |
Data type |
Definition |
notificationDestination |
Link |
Callback reference provided by the SCS/AS during creation or modification of the PFD management transaction. |
5.11.3A.2.3 Standard Methods
5.11.3A.2.3.1 Notification via POST
The HTTP POST method reports the asynchronous PFD management result. The SCEF shall initiate the HTTP POST request message and the SCS/AS shall respond to the message.
This method shall support the request data structures specified in table 5.11.3A.2.3.1-1 and the response data structures and response codes specified in table 5.11.3A.2.3.1-2.
Table 5.11.3A.2.3.1-1: Data structures supported by the POST Request Body
Data type |
Cardinality |
Description |
PfdReport |
1..N |
The PFD management notification provided by the SCEF. |
Table 5.11.3A.2.3.1-2: Data structures supported by the POST Response Body
Data type |
Cardinality |
Response codes |
Description |
none |
204 No Content |
The PFD management notification is received successfully. |
|
none |
307 Temporary Redirect |
Temporary redirection, during notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative SCS/AS where the notification should be sent. Redirection handling is described in clause 5.2.10. |
|
none |
308 Permanent Redirect |
Permanent redirection, during notification. The response shall include a Location header field containing an alternative URI representing the end point of an alternative SCS/AS instance where the notification should be sent. Redirection handling is described in clause 5.2.10. |
|
NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 also apply. |
Table 5.11.3A.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 SCS/AS towards which the notification should be redirected. |
Table 5.11.3A.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 SCS/AS towards which the notification should be redirected. |
5.11.3A.2.3.2 Notification via Websocket
If supported by both SCS/AS and SCEF and successfully negotiated, the PfdReport may alternatively be delivered through the Websocket mechanism as defined in clause 5.2.5.4.
5.11.4 Used Features
The table below defines the features applicable to the PfdManagement API. Those features are negotiated as described in clause 5.2.7.
Table 5.11.4-1: Features used by PfdManagement API
Feature Number |
Feature |
Description |
1 |
DomainNameProtocol |
This feature supports the additional protocol matching condition for the domain name in PFD data. |
2 |
PfdMgmtNotification |
This feature supports PFD management notification. |
3 |
Notification_websocket |
The delivery of notifications over Websocket is supported according to clause 5.2.5.4. This feature requires that the Notification_test_event featute is also supported. |
4 |
Notification_test_event |
The testing of notification connection is supported according to clause 5.2.5.3. |
5 |
FailureLocation_5G |
This feature supports the notification of specific failure location area of UPF for PFD management in 5G. This feature is applicable only if PfdMgmtNotification feature is also supported. The feature supports the 5G requirement and may only be supported in 5G. |
6 |
enNB |
Indicates the support of enhancements to the northbound interfaces. |
7 |
PatchUpdate |
Indicates the support of enhancements to the northbound interfaces (e.g. support the partial modification of an existing PFD Management Transaction resource). |
5.11.5 Error handling
5.11.5.1 General
HTTP error handling shall be supported as specified in clause 5.2.6.
In addition, the requirements in the following clauses shall apply.
5.11.5.2 Protocol Errors
In this Release of the specification, there are no additional protocol errors applicable for the PfdManagement API.
5.11.5.3 Application Errors
The application errors defined for PfdManagement API are listed in table 5.11.5.3-1.
Table 5.11.5.3-1: Application errors
Application Error |
HTTP status code |
Description |
Applicability |