Discussion on Links Relations and Link Decorations

[smizell]

Per discussion on Twitter and issue #8, I'm starting a new issue.

as mentioned on twitter to me this looks too minimal. for linking to be meaningful you need affordances, just having URIs usually doesn't cut it. https://github.com/dret/hyperpedia/blob/master/concepts.md is an abstract list i came up with a while ago. the current work on https://tools.ietf.org/html/draft-wilde-linkset-link-rel is a more concrete list and representation of how to do (some of) this. i think there are different ways in which you can approach this (and different people have different preferences), but calling it "RESTful" and having no model for affordances seems a bit odd to me.

This discussion is around whether or not the RESTful JSON pattern can properly provide links given it's limitations.

[smizell]

@dret I'm curious if you'd like to continue this discussion by maybe providing an example of where the pattern of RESTful JSON lacks in the ability to providing linking ability. Would you be able to help me understand your concern more? Thanks!

[fosrias]

@smizell @dret The way I look at this w/r to affordances is the the prefix of a URL has the link relation semantics. The presence of a url is not the presence of a link, but rather the presence of an affordance. A human would need to read the (HTML) docs to know exactly what to do with it and a machine could read an OAS 3 links spec, etc to know what to do with it. It is all affordances and maps straight into ALPS as well that could also give insight into the fact that they are transitions.

[dret]

i am not sure this can be well discussed on github. to me, this looks like a very minimal "type convention" for JSON, assuming that if a key follows a certain pattern, then the assumption is that the value has a certain type. that's about it. whether that's enough to provide a meaningful facility on its own (and warrants the REST title in its name) is probably just a matter of perspective. personally, when it comes to types i'd rather look at JSON schema, and when it comes to linking i'd rather look at JSON hyperschema. but of course these come with much bigger models around them. for me, the ideal size might be somewhere in the middle between these two, but again, that's just how i see things and what meaningful "module sizes" might be.

[smizell]

@dret This may be something to clarify in the document—I think you're bringing it to light because we don't mention this specifically. The rules for adding links to the JSON are for API providers. The consumers should not infer any type information from the pattern provided of url and *_url but rather should rely on JSON Schemas found in something like an OpenAPI document or MSON in an API Blueprint document. API providers are free to put links into their JSON however they want of course and do not have to follow this pattern. This is also how these patterns can be used in the context of ALPS along with existing link relation types without explicitly defining the type in the response.

RESTful JSON falls into the paradigm of building domain-specific clients. General purpose clients can infer type from media type and link relations, but that's not what we're shooting for here (though it is the more-robust approach by far). Domain-specific clients are by far the most prevalent with the most tooling out there, so it's mostly an attempt to get hypermedia into an existing, common pattern, albeit giving up some of the long-term evolvability that general-purpose clients can provide.

Regarding the name including "REST," it's a little bit of a word game. We know it doesn't fit into modern thoughts of building hypermedia APIs. But the idea is to push people a small step forward in using hypermedia to drive application state. In other words, if you have "normal JSON," you can make it "RESTful" by adding some links and conveying state through the presence/absence of links. This allows clients to be driven by that hypermedia and can get providers and consumers long way down the road. This is what I'm seeing so far in discussions with people.

[dret]

On 2017-09-14 15:43, Stephen Mizell wrote:

@dret https://github.com/dret This may be something to clarify in the document—I think you're bringing it to light because we don't mention this specifically. The rules for adding links to the JSON is for API providers. The consumers should not infer any type information from the pattern provided of |url| and |*_url| but rather should rely on JSON Schemas found in something like an OpenAPI document or MSON in an API Blueprint document. API providers are free to put links into their JSON however they want of course and do not have to follow this pattern. This is also how these patterns can be used in the context of ALPS along with existing link relation types without explicitly defining the type in the response.

but then it really is a naming convention only and the relation type in the end is not even reliably communicated via that convention, but instead through a richer linking language layered on top.

Regarding the name including "REST," it's a little bit of a word game. We know it doesn't fit into modern thoughts of building hypermedia APIs. But the idea is to push people a small step forward in using hypermedia to drive application state. In other words, if you have "normal JSON," you can make it "RESTful" by adding some links and conveying state through the presence/absence of links. This allows clients to be driven by that hypermedia and can get providers and consumers long way down the road. This is what I'm seeing so far in discussions with people.

still not really convinced. if you want to help people make a step, give them enough to make a useful step. it could be a richer model in your spec, a link set link object (https://tools.ietf.org/html/draft-wilde-linkset-01#section-4.2.2, something @hvdsomp and i have been working on for a little while), or some other existing format such as HAL. i am not convinced that the best way to guide people towards hypermedia is to give them such an extremely minimal starting point. they might get confused and lost and then start blaming the hypermedia approach for it.

[smizell]

i am not convinced that the best way to guide people towards hypermedia is to give them such an extremely minimal starting point. they might get confused and lost and then start blaming the hypermedia approach for it.

That is a fair point for sure. I have found the opposite (so far) personally. I've worked with people to understand hypermedia conceptually, which took quite a bit of time and effort. In implementing these ideas, I would direct them to HAL or Siren, leading them on a hunt for how to use these standards and decide on why to pick one or the other. Documenting link relations and profiles became quite a hurdle, however, and resulted in the need for more tools and libraries to jump from application/json to application/hal+json. The long-term payoff was eclipsed by the short-term complexity, especially the burden on their customers to learn HAL and these new concepts.

When I use this RESTful JSON pattern, people get it without even having to understand hypermedia conceptually. They get to use their current tools and even document it in their existing OpenAPI document. They continue using application/json and direct clients to documentation for understanding. Of course, they aren't formally documenting link relation types or even creating profiles, but that's OK to me if it's OK to them.

This all fits a very specific use for people, such as people who have existing APIs and want to add hypermedia controls and people who are well-versed in the modern view of RESTish APIs that want to continue to use application/json and exiting API description formats. So far, it's been a success in my experience at getting people to start thinking in terms of hyperlinking, but we'll have to see that over time.

but then it really is a naming convention only and the relation type in the end is not even reliably communicated via that convention, but instead through a richer linking language layered on top.

I don't think I would deny this (though not speaking for @fosrias) :). We have purposely stayed away from calling it a spec, creating a media type, or anything else other than calling it a pattern. It's a common way that is used across the industry in adding links to domain-specific APIs, and we're just capturing it.

Regarding the need for a richer linking language, we feel it is already present in APIs people are building through API description formats, which means there is nothing else needed to add to start documenting their links. We even think that it will work with the new Link object in OAS (we will see). This pattern is then directly dependent on some outside documentation, and I think we've bought into that.

Lastly, I admittedly need to spend more time with your link set spec, so I can't comment if I think it would be a better model for newcomers. But I will check it out.

Thanks for this discussion. It's appreciated and very needed. I'm already learning a lot in areas we can improve what we have.

[smizell]

Closing the conversation for now. Thanks for the good discussion here @dret!