Open rosscado opened 6 years ago
Under the proposed Strict Object Links approach all complex objects that are individually addressable have id
and href
attributes.
Relationships to complex objects are represented with the href
attribute only.
relation:
href: url_for_object
Example:
club:
href: /clubs/lrcc
id
: A globally unique identifier
href
: A resources href
attribute is always a function of the endpoint and id
values
Complex objects are not embedded unless explicitly requested with embed
query parameter /$resource?embed=($relation,...)
.
How should the API model represent referenced entities, especially entities that are shared?
For example, a single
Circuit
entity may be referenced by manyEvent
entities. Should theEvent
nest theCircuit
as acircuit: {CIRCUIT}
field, point to the external object's primary keycircuit_id: {circuit_uuid}
, or point to the object's URIcircuit: {circuit_url}
?Options
fields.Nested
fields.String
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 asHyperlinkRelated
. Python Eve generates a HATEOASlinks
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
.The 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:links.{relationship}.href
) and actions (HTTP methods) PUT or DELETE self GET, PUT, or DELETE racesThe 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}
Originally posted by @rosscado in https://github.com/rosscado/raceready/issues/57#issuecomment-420972983