Skip to content

Instantly share code, notes, and snippets.

@zdne

zdne/modeling.markdown

Last active August 29, 2015 13:56
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save zdne/9215380 to your computer and use it in GitHub Desktop.
Save zdne/9215380 to your computer and use it in GitHub Desktop.
Download ZIP
Modeling API: Attributes vs. Relations vs. Affordances
Raw
modeling.markdown

Modeling API

Question: Affordances or web link relations for modeling your API?

I have been pondering this question a lot lately. Given a resource and its attributes (semantic descriptors), would you model the API using the link / relations or resource affordances? May one relation as defined by RFC5988 Web Linking imply multiple affordances? For example does the edit relation represents three affordances (retrieve, update, and delete)?

Is (should?) the perspective affordances vs. relations differ based on the point of view (API design, client, server).

Most of the hypermedia media types such as HAL, Collection+JSON and JSON API are built around link relations. Seems that only Siren and to some extent the Hyper JSON distinguish between links and affordances (actions).

Is HATEOAS "dictating" us to stay in the boundaries of relations?

The media types used for these representations, and the link relations they may contain, are standardized. The client transitions through application states by selecting from the links within a representation or by manipulating the representation in other ways afforded by its media type (source: http://en.wikipedia.org/wiki/HATEOAS)

In Resource Blueprint we model API resource using attributes, affordances and its states. It feels more natural to think about the actions than the link relations while modeling an API. However the "transport" layer (aforementioned media types) and the HATEOAS principles seems to force us to use relations.

Is it easier for a client to consume relations (understand the semantics) than consume affordances? My concern here is that designing APIs with affordances and then "projecting" them into relations brings more unwanted complexity...

Thoughts? Please share your comments in the discussion bellow.

Example

Following picture is a mind map of an API with three different approaches:

  1. Attributes (semantic descriptors) only
  2. Links relations & attributes
  3. Affordances & attributes

Note attributes are marked with @.

models

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment