Content for TS 29.501 Word version: 18.4.0

1… 4… 4.3… 4.4… 4.6… 4.6.2… 4.7… 4.8… 4.9… 4.10 5… 5.2… 5.3… 6… A… D E…

4.9 Transferring multiple resources to a NF Service Consumer 4.9.1 General 4.9.2 Direct Delivery 4.9.3 Direct Delivery with Iterations 4.9.4 Indirect Delivery 4.9.5 Indirect Delivery with HTTP/2 Server Push 4.9.6 Criteria for choosing the transfer method
...

4.9 Transferring multiple resources to a NF Service Consumer p. 37

4.9.1 General p. 37

This clause describes some possible options that an API may implement when a NF Service Producer needs to return the representations of multiple resources to a NF Service Consumer, e.g. during the query of a large collection of resources (see clause 4.6.1.1.2.2).

Which options an API may support is defined in the respective stage 3 specification of the API.

4.9.2 Direct Delivery p. 37

A NF Service Producer may return the representations of the resources directly in the response body, i.e. the response body contains an array of the resource representations.

4.9.3 Direct Delivery with Iterations p. 37

If a large number of resource representations need to be returned, the NF Service Producer may return a representation containing a partial list of the requested resources in the response body, with link(s) containing URI(s) allowing the client to retrieve the remaining part(s) of the resources.

The returned representation containing a partial list of the requested resource is a "3gppHal+json" document. The document is a JSON object with two members whose names are below.

_links.
child: contains the resources of the partial list.

The member whose name is "_links" shall contain a member whose name is "self" and whose value is a "link" object that contains the URI of the returned representation. It shall also contain a member whose name is "next" and whose value is a "link" object that contains the URI of the next partial list of the collection if the returned partial list is not the last one.

The member whose name is "_links" should also contain members whose names are "first", "previous" and "last" and whose values contain a "link" object that contains the URIs of the first, previous and last partial lists of the collection if such lists exist.

The returned representation shall have a member whose name is "child" and whose value is an array of objects. Each of the individual resource representations returned in the partial list shall be embedded in an object of that array. Each object shall also have a member whose name is "_links". The later shall contain a member whose name is "self" and whose value is a "link" object that contains the URI of the embedded representation.

The Table below provides a template to be added in the clause describing the GET operation of a 3GPP API using the direct delivery with iteration mechanism.

Table 4.9.3-1: Data structures supported by the GET Response Body on this resource

Data type	P	Cardinality	Response codes	Description
PartialList	M	1	200 OK	This case represents a successful return of a partial list for the corresponding request with direct delivery with iteration.

The following data types shall be added to the list of specific data types and described as below in the structured data type clause.

Table 4.9.3-2: PartialList

Attribute name	Data type	P	Cardinality	Description
_links	map(LinksValueSchema)	M	1..N	contains the pagination links
child	array(ApiSpecificHypermediaEnabledIndividualResource)	M	1..N	contains the individual resources with a self link. The data type in the array is specific to the API and is a hypermedia enabled version of the individual resource data type.

Table 4.9.3-3: ApiSpecificHypermediaEnabledIndividualResource

Attribute name	Data type	P	Cardinality	Description
attribute1
attribute2
…
attribute N
_links	selfLink	M	1	contains the link to itself

The LinksValueSchema and SelfLink data types shall be added to the list of re-used data types of the 3GPP API.

A NF Service Consumer that receives link(s) in the response body may retrieve the remaining part(s) of the resources by sending GET requests towards the URI(s) contained in the link(s).

4.9.4 Indirect Delivery p. 39

A NF Service Producer may not return any requested resource representation and instead may return a representation containing only a list of links to the requested resources in the response body.

The returned representation containing the list is a "3gppHal+json" document. The document is a JSON object with one member whose name is:

_links.

This member shall contain a member whose name is "item" and whose value is an array of "link" objects. Each of the link objects contains one requested resource URI. There shall be one link object per requested resource.

It shall also contain a member whose name is "self" and whose value is a "link" object that contains the URI of the returned representation.

A NF Service Consumer that receives such a response may then send a GET request per resource URI to retrieve the requested resources from the NF Service Producer.

4.9.5 Indirect Delivery with HTTP/2 Server Push p. 39

A NF Service Producer may use HTTP/2 Server Push, if HTTP/2 Server Push is supported in the PLMN.

To use HTTP/2 Server Push, the NF Service Producer shall send PUSH_PROMISE frames in the HTTP response, with each PUSH_PROMISE frame containing a GET request targeting the URI of one resource to be transferred and the reserved stream identifier to be used for transferring the resource. Then the NF Service Producer shall send Push Responses via the corresponding reserved streams, with each Push Response containing the representation of the associated resource. The NF Service Producer shall also send links with the URIs of the resources in DATA frame(s) of the response message.

A NF Service Consumer may disable HTTP/2 Server Push by sending SETTINGS_ENABLE_PUSH parameter with value "0" on HTTP level, as specified in RFC 7540].

Reproduction of 3GPP TS 29.501, Fig. 4.9.5-1: Indirect Delivery with HTTP/2 Server Push

Figure 4.9.5-1: Indirect Delivery with HTTP/2 Server Push

Step 1.

A NF Service Consumer sends a HTTP request to get resources(s) to the NF Service Producer, e.g. a query of a collection of resources.

Step 2.

The NF Service Producer detects that multiple resources are to be returned and choose to indirectly deliver the resources with the Server Push mechanism.

Step 3.

The NF Service Producer returns multiple PUSH_PROMISE Requests before HEADERS frame and DATA frames(s) to the NF Service Consumer. Each PUSH_PROMISE Request contains the URI of one resource to be transferred and the identifier of the reserved stream used for transferring the resource. The NF Service Producer shall also send links with the URIs of the resources in DATA frame(s) of the response message.

Step 4.1-4.n.

The NF Service Producer sends Push Reponses via corresponding reserved streams. Each Push Response contains the representation of the associated resource.

Step 5.

If the NF Service Consumer does not successfully receive a resource in time, it may send a request to get that resource, using the resource URI previously received from the Push Request.

Step 5.a.

The NF Service Producer returns the data of the requested resource in the response.

4.9.6 Criteria for choosing the transfer method p. 41

The following considerations may be used to determine which method to use transfer multiple resources to a NF Service Consumer.

If the size of the representation of each resource is small, direct delivery is preferred. If the number of resources to be returned is large, the NF Service Producer may choose iterative delivery.

If the size of the representation of each resource is large, indirect delivery is preferred. If the NF Service Producer supports HTTP/2 Server Push, then:

when SETTINGS_ENABLE_PUSH parameter with value "1" has been received from the NF Service Consumer, as specified in RFC 7540, it should choose HTTP/2 Server Push to deliver the resource.
when SETTINGS_ENABLE_PUSH parameter with value "0" has been received from the NF Service Consumer, as specified in RFC 7540, it must not choose HTTP/2 Server Push to deliver the resources.
when SETTINGS_ENABLE_PUSH parameter has not been received from the NF Service Consumer, as specified in RFC 7540, it may decide whether to use HTTP/2 Server push or not, depending on other factors, e.g. operator policy, whether the client and server pertain to the same PLMN, etc.

An NF Service Producer shall use Indirect Delivery with HTTP/2 Server Push only if the NF Service Consumer (client) indicated support for accepting server pushed resource representations, via the Supported Features negotiation as specified in clause 6.6.2 of TS 29.500.