Resource Relationship Representation #58
Description
How should the API model represent referenced entities, especially entities that are shared?
For example, a single Circuit entity may be referenced by many Event entities. Should the Event nest the Circuit as a circuit: {CIRCUIT} field, point to the external object's primary key circuit_id: {circuit_uuid}, or point to the object's URI circuit: {circuit_url}?
Options
- Embeded resources -
fields.Nested - Keyed resources -
fields.String - Hyperlinked resources -
fields.Url
Hyperlinked Resources
Some consider the purest RESTful representation to require addressing resources by hyperlinks to their URIs. By responding with hyperlinks instead of primary keys the server doesn't require the client to have any implicit knowledge about how to use/lookup the primary keys.
Flask RestPlus represents such fields as fields.Url. Marshmallow represents them as HyperlinkRelated. Python Eve generates a HATEOAS links field by default, and returns primary keys unless directed to embed.
HATEOAS
According to strict hypermedia representational principles like HATEOAS relationships between resources should be represented as url-addressable links.
title: Lucan GP
id: {id}
links:
self:
href: /events/{id}
rel: self
organising_club:
- href: /clubs/lrcc
rel: club
races:
- href: /stages/{headline_race_id}
rel: race
- href: /stages/{a4_race_id}
rel: raceThe hypermedia principle theoretically supports programmatic navigation by clients by providing them with the complete set of permissible operations in every REST API response. E.g. GET /event/{id} is responded to with:
- information about the requested resource (fields or attributes)
- links to related resources (
links.{relationship}.href) and actions (HTTP methods)
** PUT or DELETE self
** GET, PUT, or DELETE races
The hypermedia principle extends from the web paradigm where servers have little control over clients; They know little more than that their clients are web browsers that may navigate across the network of resources linked to in the server's responses.
In most practical applications, and certainly in this project's case, there is much more control over the client(s) and its requirements. For us there will be one client initially (in support of a web application with possible mobile application clients added later), a JavaScript library rendering application resources in a web UI.
Object Links
A compromise approach that adopts advantages of both hypermedia and domain-application principles is to federate resources and include links to each. 1
GET /events/{id}
title: Lucan GP
id: {id}
href: /events/{id}
organised_by:
club:
title: Lucan Road Cycling Club
href: /clubs/lrcc
races:
- href: /events/{id}/races/{stage_id_a123}
- href: /events/{id}/races/{stage_id_a4W}Originally posted by @rosscado in #57 (comment)