5 Protocol

29.2013GPPRelease 17Representational State Transfer (REST) reference point between Application Function (AF) and Protocol Converter (PC)TS

5.1 Introduction

The following layers of the protocol stack for the Rx reference point between AF and PC are described in sub-clauses:

– TCP as defined in IETF RFC 793 [8] provides the communication service at the transport layer.

– An optional communication security layer can be added between the transport and the application delivery layer (see clause 7).

– The application delivery layer provides the transport of the specific application communication data using HTTP/1.1 as defined in IETF RFC 7230 [18], IETF RFC 7231 [19], IETF RFC 7232 [20], IETF RFC 7233 [21], IETF RFC 7234 [22] and IETF RFC 7235 [23].

– The specific application communication layer constitutes the transport of the XML documents. The XML schema describes the data structure, which is accepted by the Rx software applications.

Figure 5.1.1 illustrates the protocol stack of the RESTful Rx reference point.

Figure 5.1.1: Protocol stack of the RESTful Rx reference point

5.2 Transport layer

HTTP is layered over TCP, which provides a reliable transport.

PC and the AF act as HTTP client and HTTP server both. As a result the PC and the AF establish a TCP connection for each direction. This permits bidirectional communication.

AF and PC shall use persistent connections. If the AF or PC has not already initiated a persistent TCP connection at the time sending an HTTP message, AF or PC shall initiate a TCP connection before sending the HTTP message; otherwise the AF or PC shall use the persistent connection.

5.3 Application delivery layer

The application delivery layer shall use RESTful HTTP.

The application delivery layer provides the following services:

– session establishment including creation of resources, which are addressable in the path element of an URL, and setup of notification URLs

– session modification, termination and gate related procedures by HTTP request/response dialogs

– subscription to notifications

– notification dialog by HTTP request/response messages

– transport of the specific application communication included in the HTTP message body

Creation of resources shall be a part of the AF session establishment. The AF session ID shall be assigned by the PC and shall be used to identify the session resource at the PC. This also sets-up the notification URL, which shall be used to address the resource for notifications from the PC to the AF.

NOTE: The AF session ID is allocated by the PC. In the session dialogue the AF session ID will be used to address a resource. If it is allocated by the PC, the client will be informed about the AF session ID within the HTTP response 201 Created. This means that the session related URI (see sub-clause 5.3.4 …sessions/afsessionid) is dynamically discovered and not defined by the client.

The AF session ID is defined in subclause 5.3.5.

The Rx application requires that the PC can notify the AF about traffic plane events. The AF normally acts as the HTTP client, but the requirement for notifications result in a reversal role of the client and server. Therefore, PC and AF may act as HTTP client and HTTP server both.

If the AF establishes an AF session (i.e. initiates the initial provisioning of session information), the AF shall send an HTTP POST message to the PC including all session information required. The AF shall include the URL, which shall be used by the PC when the PC will report traffic plane events corresponding to the AF session. The PC shall allocate a new AF session ID for the AF session and shall establish an Rx Diameter session with a new Rx Diameter session ID. The PC shall keep the mapping between the AF session ID and the URL and the mapping between the AF session ID and the Rx Diameter session ID. The PC shall send an HTTP 201 CREATED response to the AF including the allocated AF session ID once it receives a response from the PCRF.

If the AF modifies an AF session (i.e. initiates modification of session information), the AF shall send an HTTP PUT message, which includes the AF session ID as a path element of the URI. The PC shall send an HTTP 200 OK response to the AF after update of the corresponding Rx Diameter session.

If the AF terminates an AF session, the AF shall send an HTTP DELETE message including the AF session ID as a path element of the URI. The PC shall send an HTTP 200 OK response to the AF after termination of the corresponding Rx Diameter session.

If the AF initializes a gate related procedure, the AF shall send an HTTP PUT to the PC including all information required. The PC shall send an HTTP response to the AF after update of the corresponding Rx Diameter session.

If the AF subscribes to notifications of the status of the signalling transmission path, the AF shall send an HTTP POST to the PC including event information for the subscription. The subscription to notifications is performed as a separate session. The PC shall send an HTTP 201 CREATED response to the AF after update of the corresponding Rx Diameter session.

When the PC reports traffic plane events corresponding to the AF session, the PC shall send an HTTP PUT to the AF using the notification URL. The request includes the AF session ID as a path element of the notification URL. The AF may use the information for appropriate actions and will send an HTTP 200 OK response to the PC.

Every HTTP message contains the specific communication information required for this case in its body.

Annex A provides call flows for all procedures.

5.3.1 Methods

Methods indicate to the server what action has to be performed. Every HTTP request message has a method. The following HTTP methods as defined in IETF RFC 7231 [19] can be used:

– POST: Used to create a resource state. The URI defines the address responsible for the creation of the resource.

– PUT: Used to modify a resource state. The URI defines the resource which will be modified.

– DELETE: Used to delete a resource state.

Every HTTP request results in a response message that comes back with a status code and further information in its body, if required. The AF waits for this response before initiating a further request for the same AF session.

5.3.2 Void

5.3.3 Resources and URI design

REST claims that the session state is held by the client or it is transferred into a resource state by the server, in order to allow a stateless communication. The concept of the resource state avoids the transfer of the complete resource state to the client. Therefore, resources shall be an integral part of the REST-Rx interface. Resources are identifiable and have state representation.

NOTE 1: Stateless communication reduces the coupling of client and server. E.g., two requests that follow each other may not be processed by the same server instance.

NOTE 2: Resources may have one or more representations. JSON may be another representation (3GPP TR 29.817 [2]). It is possible to use different representations of resources for different requirements. In this release XML will be used as a representation only.

Resources shall be identified by URIs. The URI design shall be based on the structure defined in IETF RFC 3986 [10]:

scheme ":" hier-part [ "?" query ] [ "#" fragment ]
hier-part = "//" authority path-abempty
/ path-absolute
/ path-rootless
/ path-empty

The URI design for the REST-Rx interface shall be based on the characteristics and requirements of the reference point between AF and PC and shall have a hierarchical structure.

The scheme may be HTTP or HTTPS for the REST-Rx interface. Within a scheme the definition of names shall follow the rules of HTTP URIs. Host and port are the main parts of the authority. The path element identifies the resources. The URIs, which are allowed on the REST-Rx interface and build out of the obligatory parts, shall have the structure:

Scheme://Host/Mainapplication/Mainresources

The obligatory parts have the meaning:

– Scheme: The application delivery layer protocol HTTP or HTTPS.

– Host: This part of the URI represents the server address including the port.

– Main application: The application which shall be accessed by the request. This release shall only provide the Rx application.

NOTE 3: The main application level makes possible defining different applications as resources at the same entity. This release only provides the Rx application.

– Main resources: Sessions are the core concepts of the REST-Rx interface and can be defined as the main resources by URIs. Main resources may be split into sub-resources further (e.g. individual sessions may be identified by AF session IDs).

The URI addressing of the main resource sessions can look like:

– http://pcserver/rxapplication/sessions

5.3.4 HTTP request/response dialogues

The HTTP request/response dialogue may consist out of different dialogues providing the functionalities for session establishment, modification, termination, gate related procedures, subscription to notifications and notifications. These dialogues shall include the required content translated from the Diameter messages as defined in 3GPP TS 29.214 [4] and represented by the specific application communication language as defined in sub-clause 5.4. Sessions are addressed as resources in the path of the URI.

The HTTP request message, which is related to a session establishment procedure, shall use the POST method and shall include the notification URL in addition to the required content of an AAR message XML representation. The message addresses a resource, which is responsible for resource creation and session establishment, and has the general structure:

HTTP POST https://pcserver/rxapplication/sessions

<Settings>

<NotificationBaseURL>https://afresponsehost/path</NotificationBaseURL>

</Settings>

<AA-Request>

<xs:annotation>

<xs:documentation>========================</xs:documentation>

<xs:documentation>Rx specific information/xs:documentation>

<xs:documentation>========================</xs:documentation>

</xs:annotation>

</AA-Request>

This HTTP POST message instructs the PC to create a resource state with a notification URL and to establish an AF session between the PC and the PCRF. An AAA message, received by the PC, will result in a 201 Created response, which shall include the required content to be translated from the Diameter AAA answer message as a representation of the AAA message. The response message shall include one resource in the Location header field, which represents the AF session ID and will be used as a resource address by the AF.

The HTTP request message, which is related to a session with an AF session ID, shall have the general structure:

HTTP METHOD https://pcserver/rxapplication/sessions/afsessionid

<RxMessage> < !– The actual element sent is the xml document is one of :

AA-Request, ST-Request, RA-Request or AS-Request –>

<xs:annotation>

<xs:documentation>=============================</xs:documentation>

<xs:documentation>Rx specific information/xs:documentation>

<xs:documentation>=============================</xs:documentation>

</xs:annotation>

</RxMessage>

It is answered by an HTTP response message that includes the correct content translated from a Diameter answer message as a representation as defined in Annex B.2. The HTTP response message shall have the general structure:

HTTP STATUS_CODE REASON_PHRASE

<RxMessage> < !– The actual element sent is the xml document is one of :

AA-Answer, ST- Answer, RA-Request or AS-Request –>

<xs:annotation>

<xs:documentation>=============================</xs:documentation>

<xs:documentation>Rx specific answer messages </xs:documentation>

<xs:documentation>=============================</xs:documentation>

</xs:annotation>

</RxMessage>

The definition of sessions as resources makes it possible to use HTTP methods to retrieve information about the sessions and control their state.

Table 5.3.4.1: Rx methods and their result

Method	Result
POST …/sessions	Creates a resource for a session and initiates an AF session establishment procedure
PUT …sessions/afsessionid	Modifies a session/resource state or initates a gate related procedure. “afsessionid” is the AF session resource id that was previously created by the PC and returned in the Location header within the answer to the POST message.
PUT …<notificationbaseurl>/<afsessionid>	Notifies the AF about traffic plane events associated with an AF session. The “notificationbaseurl” is set to the received NotificationBaseURL value in the original POST message that created the corresponding AF session resource. The “afsessionid” is the AF session resource id that was previously created by the PC and returned in the Location header within the answer to the POST message.
DELETE …sessions/<afsessionid>	Deletes a session/resource state. The “afsessionid” is the AF session resource id that was previously created by the PC and returned within the answer to the POST message.

5.3.5 AF Session ID

The Diameter session between the PC and PCRF is mapped to a resource on the REST-Rx interface. The AF uses the AF session ID allocated by the PC, in the path element of an HTTP method to address the PC resource, which is used as an address for events corresponding to a particular activity. When the PC reports traffic plane events corresponding to the AF session, the PC adds the AF session ID as a path element to the notification URL.

The syntax of the Session ID defined for IETF RFC 6733 [17] can be mapped to the AF Session ID. The format of the AF session ID shall follow the implementation-specific syntax standardized for path elements of URLs [15]. The delimiter ";", which is used in the Diameter Session ID definition, need not be percent-encoded since there will be no conflict with a reserved character of the URI component.

NOTE: Characters in the reserved set are protected from normalization and are therefore safe to be used by scheme-specific and producer-specific algorithms for delimiting data subcomponents within a URI [15].

5.4 Specific application communication

5.4.0 General

Specific application communication represents the presentation of application data structures by transforming data into the form that the application accepts. It establishes the context between application-layer entities.

Note: This release only supports the content type XML.

5.4.1 Content type XML

The content type of the RESTful HTTP message shall be XML.

5.4.1.1 XML schema

The XML schema is given in annex B.

5.4.1.2 Data types and mapping between XML elements

The mapping between the Diameter value types or other parameter types used in this specification and the XML simple types is defined in table 5.4.1.2.1.

Table 5.4.1.2.1: Mapping between Diameter AVPs, other types and XML types

Diameter Value Type or other type	XML Simple Type	Remark
Enumerated	unsignedInt, integer	In XML enumerations constrain the value space to a specified set of values defined in TS 29.214 [4]. Integer or unsignedInt is selected as the XML type.
IPFilterRule	string	The Diameter IPFilterRule is derived from OctetString. The IPFilterRule uses the ASCII charset.
OctetString	hexBinary	OctetStrings contain arbitrary data of variable length. They are used to process arrays of byte values. The data type is not limited to string values but can store any byte based data type (including binary data).
Time	unsignedLong	The time format is derived from the OctetString AVP Base Format. The string must contain four octets, in the same format as the first four bytes of the NTP timestamp format. The 64-bit timestamp format is used on the REST-Rx interface. It includes a 32-bit unsigned seconds field spanning 136 years and a 32-bit fraction field resolving 232 picoseconds.
Unsigned32	unsignedInt
Unsigned64	unsignedLong
UTF8String	string	The UTF8String is derived from the OctetString the base format.
Binary data	hexBinary	hexBinary represents arbitrary hex-encoded binary data.
Integer (used as enumeration indication)	unsignedInt	The unsigned integer can be used as enumeration value.

NOTE: AVPs which are defined in 3GPP TS 29.214 [4] but not defined in the XML schema (see Annex B.1) as representations of AVPs cannot be supported on the specific application communication layer of the REST-Rx interface respectively cannot be supported for the Diameter message representation (see Annex B.2).

5.4.1.3 Mapping between Diameter AVPs and XML elements and groups

The mapping between the Diameter AVP names and XML element and group names is defined in table 5.4.1.3.1.

Table 5.4.1.3.1: Mapping between Diameter AVPs and XML elements or groups

Diameter AVP [4]	REST-Rx abbreviation	Type
3GPP-MS-TimeZone	MSTimeZone	Complex element
3GPP-SGSN-MCC-MNC	SgsnMccMnc	Complex element
3GPP-User-Location-Info	ULI	Complex element
AN-GW-Address	ANGWAddr	Simple element
AN-Trusted	ANTrusted	Simple element
Abort-Cause	AbortCause	Simple element
Acceptable-Service-Info	AcceptableSvcInfo	Group
Access-Network-Charging-Address	ANCAddr	Simple element
Access-Network-Charging-Identifier	ANCID	Group
Access-Network-Charging-Identifier-Value	ANCIDVal	Simple element
AF-Application-Identifier	AFAppId	Simple element
AF-Charging-Identifier	AFChargingId	Simple element
Application-Service-Provider-Identity	ASPId	Simple element
Called-Station-ID	APN	Simple element
CC-Input-Octets	CCIO	Simple element
CC-Output-Octets	CCOO	Simple element
CC-Total-Octets	CCTO	Simple element
Codec-Data	CodecData	Simple element
DRMP	DiaPri	Simple element
Experimental-Result	ExperiRes	Group
Experimental-Result-Code	ExperiResCode	Simple element
Extended-Max-Requested-BW-DL	ExtMaxBwDL	Simple element
Extended-Max-Requested-BW-UL	ExtMaxBwUL	Simple element
Extended-Min-Requested-BW-DL	ExtMinBWDL	Simple element
Extended-Min-Requested-BW-UL	ExtMinBWUL	Simple element
Feature-List	FeatList	Simple element
Feature-List-ID	FeatListId	Simple element
Final-Unit-Action	FinUnitAct	Simple element
Flow-Description	FlowDesc	Simple element
Flow-Number	FlowNum	Simple element
Flow-Status	FlowStatus	Simple element
Flow-Usage	FlowUsage	Simple element
Flows	Flows	Group
Framed-IP-Address	UEIP	Simple element
Framed-IPv6-Prefix	UEIPv6	Simple element
Granted-Service-Unit	GSU	Group
IP-CAN-Type	IPCANType	Simple element
IP-Domain-ID	IPDomainId	Simple element
Max-Requested-Bandwidth-DL	MaxBwDL	Simple element
Max-Requested-Bandwidth-UL	MaxBwUL	Simple element
Media-Component-Number	MCN	Simple element
Media-Component-Description	MCD	Group
Media-Sub-Component	MSC	Group
Media-Type	MediaType	Simple element
Min-Requested-Bandwidth-DL	MinBWDL	Simple element
Min-Requested-Bandwidth-UL	MinBWUL	Simple element
MPS-Identifier	MPSId	Simple element
NetLoc-Access-Support	NETLocAccSupp	Simple element
Origin-State-ID	OrigStateId	Simple element
RAN-NAS-Release-Cause	RANNASRelCause	Complex element
RAT-Type	RATType	Simple element
Reference-Id	RefId	Simple element
Required-Access-Info	ReqAccInfo	Simple element
Reservation-Priority	ResPrio	Simple element
Result-Code	ResCode	Simple element
Retry-Interval	RetryInterval	Simple element
RR-Bandwidth	RRBw	Simple element
RS-Bandwidth	RSBw	Simple element
Rx-Request-Type	ReqType	Simple element
Service-Info-Status	SvcInfoStatus	Simple element
Service-URN	SvcURN	Simple element
Specific-Action	SpecificAction	Simple element
Sponsoring-Action	SponsAct	Simple element
Sponsor-Identity	SponsId	Simple element
Sponsored-Connectivity-Data	SpConnData	Group
Subscription-ID	SubId	Group
Subscription-ID-Data	SubIdVal	Simple element
Subscription-ID-Type	SubIdType	Simple element
Supported-Features	SuppFeatures	Group
TCP-Source-Port	TCPSrcPort	Simple element
Termination-Cause	TermCause	Simple element
TWAN-Identifier	TWANId	Simple element
ToS‑Traffic‑Class	TTC	Simple element
UDP-Source-Port	UDPSrcPort	Simple element
UE-Local-IP-Address	UELocalIP	Simple element
Used-Service-Unit	USU	Group
User-Location-Info-Time	ULITime	Simple element
Vendor-ID	VenID	Simple element

NOTE 1: Diameter AVPs which are listed in 3GPP TS 29.214 [4] but not listed in table 5.4.1.3.1 will not be supported on the specific application communication layer of the REST-Rx interface.

NOTE 2: When the Diameter message transports the Result Code AVP or an Experimental Result Code AVP, for example, the PC need not inspect these AVPs and need not map these AVPs to HTTP status codes. The AVPs shall be included into HTTP commands as representations and will be transported between the endpoints (PCRF and AF), which are responsible to take this information into account.

5.5 PC discovery

The Dynamic Host Configuration Protocol (DHCP) [12] and Domain Name System (DNS) [11] interfaces are typically not included in architecture diagrams or described as reference points. For the PC discovery, DHCP and DNS interactions can take place between the AF and the PC. If the AF does not have PC address information (i.e. provided by preconfiguration or other protocol configuration options), DHCP and DNS queries can be carried out before the creation of resources by the AF. The input parameters could be the UE IP address, User identity, IP domain Id and PDN Id.