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