Content for TS 29.501 Word version: 19.0.0
4.7 HATEOAS
4.7.1 General
4.7.2 3GPP hypermedia format
4.7.2.1 Basic 3GPP hypermedia format
4.7.2.2 Extended 3GPP hypermedia format
4.7.3 Advertising legitimate application state transitions
4.7.4 Inferring link relation semantic
4.7.5 Common Relation Types
4.7.5.1 Introduction
4.7.5.2 Registered relation types
4.7.5.3 Extension relation types
4.7.6 Negotiating the support of optional HATEOAS features
...
...
4.7 HATEOAS p. 32
4.7.1 General p. 32
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.
4.7.2 3GPP hypermedia format p. 32
4.7.2.1 Basic 3GPP hypermedia format |R16| p. 32
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.
| Attribute name | Data type | P | Cardinality | Description |
|---|---|---|---|---|
| _links | map | C | 0..N | _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.
4.7.2.2 Extended 3GPP hypermedia format |R16| p. 33
- "_links": contains links to other resources and expresses valid state transitions;
- "_templates": contains the HAL templates corresponding to the _links attribute.
| Attribute name | Data type | P | Cardinality | Description |
|---|---|---|---|---|
| _links | map(Link) | C | 1..N | The key is the name of the link relation type. |
| _templates | map(HalTemplate) | C | 1..N | 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.
4.7.3 Advertising legitimate application state transitions p. 33
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).
4.7.4 Inferring link relation semantic p. 34
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.
4.7.5 Common Relation Types p. 34
4.7.5.1 Introduction p. 34
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.
4.7.5.2 Registered relation types p. 34
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.
| Relation name |
|---|
| self |
| Relation name |
|---|
| next |
| first |
| previous |
| last |
| item |
4.7.5.3 Extension relation types p. 34
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.
4.7.6 Negotiating the support of optional HATEOAS features p. 35
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.
