HAL Discuss Google Group

Re: Including documentation

top...@amicushq.com (Topper Bowers) — Fri, 17 May 2013 19:13:32 UT

thank you for this! I'll have to ponder this as I'm not sure I agree with
the statement that "facebook_users" is just for humans... especially since
the destination of rel links aren't specified (they could just be html doc
pages).

However... well said!

Topper

Re: Including documentation

habi...@gmail.com (Josh Kuhn) — Fri, 17 May 2013 19:03:02 UT

Off the top of my head, benefits:
1. The rel is syntactically required in hal (try to omit it!). In html
links, humans can infer the relationship of the link from the context, but
api clients absolutely need to know "what this link means to the current
document".
2. The full rel uri doesn't have to be included in each link thanks to the

Re: Including documentation

top...@amicushq.com (Topper Bowers) — Fri, 17 May 2013 18:35:55 UT

I buy that mostly. However, it's "more spec" and "more payload" so it
should justify that with "better because..."

Topper

Re: Including documentation

deontologic...@gmail.com (Josh Kuhn) — Fri, 17 May 2013 18:20:23 UT

As for "what makes the first version better than what I proposed?", it's
just a different way of doing it. Hal gets rid of one more keyword in the
link itself by having the key be the rel, but other JSON hypermedia formats
do something very similar to what you've proposed. (
[link]), it's not at all unreasonable. Here

Re: Including documentation

deontologic...@gmail.com (Josh Kuhn) — Fri, 17 May 2013 18:16:40 UT

I think you're thinking it's much more complicated than it is. Here is a
curied version of your 1st example:

{
"name": "Acme",
"_embedded": {},
"_links": {
"self": {
href: "[link]"
},
"curies": [{
"name": "tc",
,"href": "[link]{rel}"

Re: Including documentation

top...@amicushq.com (Topper Bowers) — Fri, 17 May 2013 14:30:07 UT

Oh. Hmmm... that sounds worse to me. so then the benefits of curies are
even fewer then aren't they?

So what makes the first version better than what I proposed?

Topper

On Fri, May 17, 2013 at 10:23 AM, The Rabid Banana <therabidban...@gmail.com

Including documentation

therabidban...@gmail.com (The Rabid Banana) — Fri, 17 May 2013 14:27:08 UT

I think you're missing the part about also including the curie links in the
response. There isn't some documentation elsewhere that translates curies
into full URLs, you are need to include your curie namespace as a URI
template in the response. Something like:

_links: { curies: [{ name: 'facebook', href: 'facebookdocs/{curie}' }, {

Re: Including documentation

therabidban...@gmail.com (The Rabid Banana) — Fri, 17 May 2013 14:23:40 UT

_links: { curies: [{ name: 'facebook', href: 'facebookdocs/{curie}' }, {

Re: Including documentation

top...@amicushq.com (Topper Bowers) — Fri, 17 May 2013 13:25:52 UT

It was helpful for me too. I still don't think anyone has answered my:
"what do we get out of this in the real world" yet though and I just must
be missing something. I know I'm a little late to the party here, but can
we walk through a scenario here? I really love this spec and want to see it

Re: Including documentation

kevin.w.br...@gmail.com (Kevin Brown) — Fri, 17 May 2013 12:52:59 UT

For me ( who hasn't used curries yet) this explanation is helpful. Thanks Jørn.

Re: Including documentation

mikekelly...@gmail.com (Mike Kelly) — Fri, 17 May 2013 11:26:24 UT

they are, but the server should not expect to be able to rename the
curie token to something else and expect the clients to work.

Cheers,
M

Re: Including documentation

j...@fjeldgruppen.dk (Jørn Wildt) — Fri, 17 May 2013 11:10:21 UT

Duh? I certainly also expected it to be the other way around: the curie
token is simply a shorthand/alias for the URI, meaning:

// Curie "bug" is defined as href = "[link]"
// So the two lines below should be considered equivalent:

_links["bug:report"] ...
_links["[link]"] ...

Re: Including documentation

mikekelly...@gmail.com (Mike Kelly) — Fri, 17 May 2013 11:02:47 UT

That is absolutely not the intended design of curies in hal+json. The
token is what matters, and the URI should be able to change. Perhaps
this is something that needs clarifying in the spec? Was anyone else
under the impression this was the case?

Cheers,
M

--
Mike

[link]

RE: Including documentation

jos...@gmail.com (Josh Cohen) — Thu, 16 May 2013 23:10:09 UT

This may be a slightly different point than Topper is making but...

[JoshCo] A challenge I see here is that the prefix 'xyz' can vary. It
reminds me of XML namespaces. Eg, you aren't supposed to hardcode the
prefix because you need to be prepared for it to be any string. It can also
vary across multiple request responses.

Re: Including documentation

mikekelly...@gmail.com (Mike Kelly) — Thu, 16 May 2013 23:05:23 UT

Ok then I don't really understand the point you're making, sorry

--
Mike

[link]
[link]
[link]