Suggestion to employ HATEOAS for relationships if REST is the chosen API style

[germanandy]

The RFC visits the topic of Objects and their Relationships to each other in a number of places.

In the payload Metadata, the field 'ParentId' appears.

The inclusion of 'ParentId' in the metadata for the object payload indicates that the API design assumes it can arrive at a finite set of ideal relationships - parent/child in hierarchies and then ad-hoc relationships, etc.

This is a more involved problem than it first appears.

In a non-trivial object model, the relationships can become quite complex and hard to represent.

Hierarchies come in several different flavours:

• Composition/Aggregation Hierarchies (has-a):
  • 'Site A' has-a 'Area X' which has-a 'Line 5' which has-a 'Mixing vessel A'
• Inheritance (is-a):
  • 'Mixing vessel A' is-a instance of 'MixingVessel' which is-a subclass of 'Vessel'
• Association:
  • 'Mixing vessel A' Feeds-into 'Fermentation Vessel B'

There are more types but these are typical.

As the system grows in complexity the schema could be repeatedly modified to accommodate new relationships, resulting in overloading or misusing existing fields.

SUGGESTION IF USING REST AS THE API ARCHITECTURAL STYLE - Embed the relationships in the HATEOAS links.

HATEOAS Principle
This principle first appeared in Roy Fielding's original REST dissertation and it is underutilised but quite a neat fit here
https://en.wikipedia.org/wiki/REST
https://en.wikipedia.org/wiki/HATEOAS

Put the relationships in the links section via HATEOAS
Put the relationships in the links section and leave it dynamic, establish a few conventions about what kind of relationships could appear there. Note the MQTT subscribe link in the example below.

{
  "elementId": "mixing_vessel_a",
  "DataType": "Object",
  "properties": {
    // Properties specific to Mixing Vessel A
  },
  "links": [
    {
      "rel": "belongs-to",
      "href": "/org/site_a/areas/area_x/lines/line_5",
      "elementId": "line_5"
    },
    {
      "rel": "is-a",
      "href": "/classes/mixing_vessel",
      "elementId": "mixing_vessel_class"
    },
    {
      "rel": "feeds-into",
      "href": "/org/site_a/areas/area_x/lines/line_5/fermentation_vessel_b",
      "elementId": "fermentation_vessel_b"
    },
    {
      "rel": "mqtt-subscribe",
      "href": "mqtt://broker.example.com/mixing_vessel_a/data",
      "title": "MQTT Data Subscription for Mixing Vessel A"
    },
    {
      "rel": "has-a",
      "children": [
        {
          "href": "/org/site_a/areas/area_x/lines/line_5/mixing_vessel_a/agitation_system",
          "elementId": "agitation_system",
        },
        {
          "href": "/org/site_a/areas/area_x/lines/line_5/mixing_vessel_a/temperature_sensor",
          "elementId": "temperature_sensor",
        },
        {
          "href": "/org/site_a/areas/area_x/lines/line_5/mixing_vessel_a/pressure_valve",
          "elementId": "pressure_valve",

        }
      ]
    }
  ]
}

In this way you shift the responsibility of conveying relationships from the payload to the hypermedia controls within the RESTful response. This means that instead of embedding relationship identifiers directly in the data, you provide links that define how the current resource is related to others. This decouples the core data schema from its relationships, allowing each to evolve independently.

There are some downsides to this, mainly in the flexibility of the way the schema is expressed, but there may be more danger in trying to define relationships of objects inside the data model.

[randy-armstrong]

The OPC UA address space is like this. The relationships are metadata that is independent of the values. There is a separate Browse service that allows a client to request the relationships on a Element/Node. OPC UA also provides all of the mechanisms needed to model complex systems.

Many of the implementers of this API will also have knowledge of OPC UA so I think it makes sense to borrow from OPC UA when it comes down to a choice between using something else that provides the same features but is different enough to create headaches for developers.

[jwise-mfg]

@germanandy the Working Group would like to hear from a SME on this topic. Would you care to join us for a meeting, or can you recommend someone we could learn more from?

[germanandy]

Yes of course, happy to help. Let me know how we can connect and arrange

…

On Tuesday, 11 February 2025, Jonathan Wise ***@***.***> wrote: @germanandy <https://github.com/germanandy> the Working Group would like to hear from a SME on this topic. Would you care to join us for a meeting, or can you recommend someone we could learn more from? — Reply to this email directly, view it on GitHub <#5 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ATUNY4FOK5FGYCFZPB7AHS32PJ2Y5AVCNFSM6AAAAABRN5KT2WVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMNJSGIYDQNRVGY> . You are receiving this because you were mentioned.Message ID: ***@***.***>

--

____________________________________ Andy German

[jwise-mfg]

@germanandy sent you a message on LinkedIn, thanks!

[jwise-mfg]

@germanandy and Niels Andersen from LNS invited for March 11 WG meeting as SMEs.