How should HATEOAS Links in a json response be handled and why? - API Craft

The old Google Groups will be going away soon, but your browser is incompatible with the new version.
Message from discussion How should HATEOAS Links in a json response be handled and why?
Received-SPF: pass (google.com: domain of mikekelly...@gmail.com designates 209.85.214.172 as permitted sender) client-ip=209.85.214.172;
MIME-Version: 1.0
In-Reply-To: <5040a8a8-1622-40c5-aed2-9933e65d4851@googlegroups.com>
References: <e798a1ea-1dc6-4079-af2d-dda8e7f7f3f0@googlegroups.com>
	<f725c08c-f36d-4650-8910-6e3430b361e7@googlegroups.com>
	<7A0172D5-36CB-49D0-9AFE-7887CC642...@gmail.com>
	<CAG=1cLWE_smb6+7BNZta1UsLrQ36-Q53Y2=fHdxu91dZh4-...@mail.gmail.com>
	<AFB43C4F-B98A-4951-BE91-9926D17A8...@gmail.com>
	<5040a8a8-1622-40c5-aed2-9933e65d4851@googlegroups.com>
Date: Thu, 25 Oct 2012 11:21:44 +0100
Message-ID: <CANqiZJZKSvmhiRUX2T_szwVETzYuynTs2J60Zh333XPHx34...@mail.gmail.com>
Subject: Re: [api-craft] Re: How should HATEOAS Links in a json response be
 handled and why?
From: Mike Kelly <mikekelly...@gmail.com>
To: api-craft@googlegroups.com
Content-Type: text/plain; charset=ISO-8859-1

On Thu, Oct 25, 2012 at 6:03 AM, Dave Gauer <ratfac...@gmail.com> wrote:
> On Wednesday, October 24, 2012 12:52:29 AM UTC-7, Mike Kelly wrote:
>> Hi David,
>>
>> Link relations are the primary identifier of links, so they're a pivotal
>> part of your hypermedia type's interface that need to be as accessible as
>> possible. They're the only property that's required of a link other than the
>> target URI. The vast majority, if not all, client interactions with an
>> hypermedia API will be primarily driven by the link relations so I think
>> it's reasonable to adopt that as the general case and to optimise for it.
>
>
>
> Rel being required...what specification requires a rel property?  I didn't
> think REST or the concept of HATEOAS got that specific.
>
> But I'm sure you're right that any sort of automated discovery of link
> relations would rely heavily on (or at least benefit greatly from) on a good
> rel naming scheme.

Hey Dave,

The spec I was referring to was the Web Linking RFC:

http://tools.ietf.org/html/rfc5988#section-3

   In this specification, a link is a typed connection between two
   resources that are identified by Internationalised Resource
   Identifiers (IRIs) [RFC3987], and is comprised of:

   -  A context IRI,

   -  a link relation type (Section 4),

   -  a target IRI, and

   -  optionally, target attributes.


>>
>>
>> Out of interest, did you have any specific use cases that you felt the
>> array approach was better suited for?
>
>
>
> No, definitely not.  Either would work in practice.  I'm just trying to
> picture what I might want as a consumer of an API.  I think it's very
> difficult to predict how clients will use returned data.  An array seems to
> me to assume the least.

Well a link isn't just any old data and the rel isn't any old
property, right? Link relations are a required part of a link because
they are the primary means of identification, so given that I don't
think it's difficult or unreasonable to predict/assume that almost all
client usage of links will revolve around them. JSON gives us a
'native' way to model the relations and their links as key/value via
the JSON Object and makes the links easier to get to, so I think it
makes sense to play to JSON's strengths here.

In fact, I would go further an argue that constraining access to links
so that they have to be accessed via their relation (i.e. the hal+json
approach) is actually an important part of its design, because it
reduces the coupling surface of the media type, for example suppose a
representation had this set of links:

links: [{
  "rel": "self",
  "href": "/thing"
},{
  "type": "application/user+json",
  "rel": "owner",
  "href": "/bar"
}]

this opens up the possibility of client code being written that
selects the owner link via the type attribute "application/user+json".
That's not good because it will break when further down the line the
representation changes to look like this:

links: [{
  "rel": "self",
  "href": "/thing"
},{
  "type": "application/user+json",
  "rel": "customer",
  "href": "/baz"
},{
  "type": "application/user+json",
  "rel": "owner",
  "href": "/bar"
}]

I agree with the principal that when designing a generic interface
that reducing assumptions is important, however in this case I think
that using link relations as the primary key to access links is a
reasonable assumption that significantly improves its usability and
robustness as an interface.

Cheers,
M
Create a group - Google Groups - Google Home - Terms of Service - Privacy Policy
Account Options
