As defined in [14], HATEOAS stands for Hypermedia As The Engine Of Application State. It means that the hypermedia models application state transitions and describe application protocols.
As defined in [15] clause 3 RESTful Domain Application Protocols, an application is a software implementation defined to achieve a particular goal. It consists of a set of constrained interactions between NF Service Consumer and Producer performed at run-time that are guided by an application specific set of rules. The application transits across some intermediate states until the application's goal is achieved. The application has then reached its final state.
An application state is a snapshot of an application instance.
On each interaction, the NF Service Consumer and Producer exchange representations of resource state. According to [14], "REST concentrates all of the control state into the representations received in response to interactions." and "The model application is therefore an engine that moves from one state to the next by examining and choosing from among the alternative state transitions in the current set of representations." After each interaction the NF Service Consumer is then presented with control state options to interact with additional resources. These control states are in the form of hypermedia markups embedded in the returned resource representation. The application state changes when an NF Service Consumer examines and chooses which control to operate and subsequently interacts with the resources identified in the selected control state.
HATEOAS support is optional. If HATEOAS is supported, the procedure in the present clause 4.7 shall apply.
Basic 3GPP hypermedia format specifies the following optional reserved properties (see TS 29.571 for the complete list and definition of objects and object members):
"_links": contains links to other resources and expresses valid state transitions.
A NF service producer shall construct a basic 3GPP hypermedia document by taking a 3GPP defined JSON object attribute list and then adding a "_links" attribute.
_links attribute to be added into the JSON hypermedia object definition
The LinksValueSchema data type shall be added to the list of re-used data types of the hypermedia enabled API (see TS 29.509 for an example of implementation of a hypermedia API).
The "_links" member names are link relation types (as defined by RFC 8288) and values are either a "link" object or an array of "link" objects.
Basic 3GPP hypermedia format specifies the following "link" attribute:
"href": contains the URI of the linked resource.
A NF service producer shall set the Content-Type HTTP header to "application/3gppHal+json" when returning an HTTP payload with a basic 3GPP hypermedia enabled document.
A NF service consumer supporting HATEOAS shall advertise it by adding an "Accept" HTTP header with "application/3gppHal+json" as media type.
Extended 3GPP hypermedia format specifies the following optional reserved properties (see TS 29.571 for the complete list and definition of objects and object members):
"_links": contains links to other resources and expresses valid state transitions;
"_templates": contains the HAL templates corresponding to the _links attribute.
A NF service producer shall construct a extended 3GPP hypermedia document by taking a 3GPP defined JSON object attribute list and then adding "_links" attribute and "_templates" attribute.
The key is the name of the corresponding link relation type to which the template is to be applied.
The Link data type and HalTemplate data type shall be added to the list of re-used data types of the hypermedia enabled API.
A NF service consumer supporting HATEOAS and extended 3GPP hypermedia shall advertise it by adding an "Accept" HTTP header with "application/3gppHalForms+json" as media type.
When a NF service producer responds to a NF service consumer and there is one or more application state transition possible, the NF service producer shall advertise them by adding a "_links" property in the returned resource representation. When there are multiple state transitions with different relation types, then one member per relation type shall be added to the "_links" object which name is equal to the relation type. If there is only one state transition for a given relation type then the value of the member is a "link" object otherwise it is an array of "link" objects.
A NF service producer shall include a link into the returned resource representation with a registered relation type "self" when it is expected further actions upon it (for instance reading it again or replacing the resource state).
When a NF service consumer receives a response with linked resources then it shall infer the link relation semantic from the relation type. It shall not infer it from the linked resource URI format.
In 3GPP hypermedia, relation types are the name of "_links" object members.
This clause contains the list of relation types supported in 3GPP Service Based Interface APIs.
As defined in Section 2.1 in RFC 8288, a link relation type identifies the semantics of a link. It describes how resources are related to each other. It may also be used to indicate that the target resource of a link has particular attributes, or exhibits particular behaviours. Relation types shall not be confused with media types. It does not identify the format of the representation that results when the link is dereferenced.
There are two kinds of relation types:
Registered relation types;
Extension relation types.
Registered relation types are identified by a token (for instance "self") and can be reused by other applications such as 3GPP SBI APIs. They are registered by IANA. Registered relation types shall be preferred against extension relation types when expressing the link relation between two resources.
If there is a need to define a relation type that does not correspond to a registered one but it is not wanted to register it then an extension relation type shall be used instead.
The "Link Relations" registry is located at: https://www.iana.org/assignments/link-relations.
Table 4.7.5.2-1 specifies the list of registered relation types supported by all hypermedia enabled 3GPP APIs.
Table 4.7.5.2-2 specifies the list of registered relation types that can be used by some hypermedia enabled 3GPP APIs, depending on the API design.
When no registered relation exists to express the relation between two resources, an extension relation type shall be used instead. It may be defined as a string token or as a URI as defined in RFC 8288.
An API specification using extension relation types shall contain a clause "Relation types" in the clause "Simple data types and enumerations" (see TS 29.509 for an example of implementation of a hypermedia API). The clause shall contain a table listing the token or the URI of the created relation types. It shall also contain a detailed specification of the semantic of the relation types defining the conditions that the NF Service Consumer shall match to follow a link.
The supported feature mechanism in clause 6.6.2 of TS 29.500 should be used to negotiate the usage of optional HATEOAS features in addition to negotiating the content type "3gppHal+json" and "3gppHalForms+json". Separate supported features can be defined for link relation types related to different use cases.
When an error occurs that prevents the NF/NF service acting as an HTTP server from successfully fulfilling the HTTP request, the NF/NF service shall map an application error to the most similar 4xx/5xx HTTP status code as defined in clause 5.2.7 of TS 29.500.
When the HTTP status code is not enough for the NF/NF service acting as an HTTP client to determine the cause of the error, the NF/NF service acting as an HTTP server should provide additional application related error information, by including in the response body a representation of a "ProblemDetails" data structure according to RFC 7807 that provides additional details of the error.
The definition of the general "ProblemDetails" data structure from RFC 7807 is specified in clause 5.2.4.1 of TS 29.571. The "ProblemDetails" data structure is a JSON object, as defined in RFC 7807, and contains the following attributes:
"type" - a URI reference according to RFC 3986 that identifies the problem type;
"title" - a short, human-readable summary of the problem type that should not change from occurrence to occurrence of the problem;
"status" - the HTTP status code for this occurrence of the problem;
"detail" - a human-readable explanation specific to this occurrence of the problem; and
"instance" - a URI reference that identifies the specific occurrence of the problem.
A particular API may define additional attributes that provide more information about the error.
The following additional attributes are generic extensions defined for the 3GPP 5GC APIs:
"cause"- a machine-readable application error cause specific to this occurrence of the problem; and
"invalidParams" - invalid parameters causing a request to be rejected.
The "cause" attribute should be included and provide application-related error information, if available. Application error causes should be defined in 5GC SBI APIs specifications, using the UPPER_WITH_UNDERSCORE case convention specified in clause 5.1.1.
EXAMPLE 1:
"OUT_OF_LADN_SA".
The "invalidParams" attribute should be used to report invalid parameters when a request is rejected due to invalid parameters.
All the application error causes supported by an API should be defined in a specific clause "Application Errors" under the "Error Handling" clause specified for the API. The application error causes that a specific service operation may respond should be further listed in the table defining the data structure supported by the response body, with the associated HTTP error status code.
To enable a SEPP or an SCP for Indirect Communications to provide error details in error responses they originate, all service operations should support returning error responses including a representation of a "ProblemDetails" data structure. If additional application specific information is required in the error responses, the API should support returning the additional applicative information as specified in clause 4.8.3. The NF/NF service that generates the HTTP response shall include in the HTTP response a "Content-Type" header field set to:
"application/problem+json", if the response includes a payload body containing the "ProblemDetails" (or extended ProblemDetails, see clause 4.8.3) data structure; or
"application/json", if the response includes a payload body containing an application-specific data structure.
For a service operation that returns "ProblemDetails" in error responses in a given release, if in a later release it is required to provide additional application specific information in the error responses, the API should be modified to return an Extended-ProblemDetails data type by reusing the "ProblemDetails" common data type, as specified in clause 5.3.17, to keep the API backward compatibility.
The "Content-Type" header shall be set to "application/problem+json" for the error response with the payload body containing the Extended-ProblemDetails data type define above.
EXAMPLE:
an "AdditionInfo<ServiceOperation>" structured data type containing the additional information to be returned, as specified in clause 5.2.4.2:
"<type>" or "array(<type>)" or "map(<type>)" or "Any Type"
"M", "C" or "O"
"0..1", "1" or "M..N"
<only if applicable>
a "ProblemDetails<ServiceOperation>" data type as combination of "ProblemDetails" common data type and "AdditionInfo<ServiceOperation>" data type define above, as specified in clause 5.2.4.5:
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.
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.
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.
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.
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).
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.
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].
The NF Service Producer detects that multiple resources are to be returned and choose to indirectly deliver the resources with the Server Push mechanism.
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.
The NF Service Producer sends Push Reponses via corresponding reserved streams. Each Push Response contains the representation of the associated resource.
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.
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.