I've made a start on an Internet Draft for hal+json:

https://raw.github.com/mikekelly/hal-rfc/master/draft-kelly-json-hal-...

Let me know if you think I've missed anything or got something wrong,
and if you're feeling really adventurous fork it, edit and raise a
pull request!! :)

Cheers,
Mike

* Should probably be explicit that templated's default value is false.
* Mentions rfc5988 but don't mention whether additional link
  params are allowed as defined in rfc5988#section-5.4. I imagine the
  idea is that since it's just JSON, you can add additional parameters
  to _links that aren't listed in the rfc, but probably best to be explicit.
  For example - is the "media" hint allowed?
* Doesn't mention being able to dereference CURIEs.

- David

This somewhat sounds like you've condemned xml-hal to death... Unless
you're planning on doing that as a separate thing.

(personally I'd prefer to keep the two together ).

On 7/06/12 1:02 PM, Mike Kelly wrote:

The former indicates a single word reltype, the later can include a
space separated list of reltypes.  I think I actually prefer the
stronger restriction as that solves an open issue/query I have with
HalBuilder currently.

Mark

On 7/06/12 1:02 PM, Mike Kelly wrote:

Cheers,
M

On 7 Jun 2012, at 02:13 AM, Mark Derricutt <m...@talios.com> wrote:

Does anyone on this list have a strong requirement for this NOT to change?

On 7 Jun 2012, at 02:19 AM, Mark Derricutt <m...@talios.com> wrote:

On 7 Jun 2012, at 03:29 PM, David Haslem <therabidban...@gmail.com> wrote:

Cheers,
M

  https://github.com/talios/halbuilder/issues/24

Basically it was a question of roundtripping XML->(internal
model)->JSON->(internal model)->XML.

If a resource is embedded with a rel of "rel1" but ALSO has a link to
its own URL with a rel of "rel2", I'm optimizing/rolling them up into a
single <link/> element, or _link node with a rel of "self rel1 rel2"
rather than having 3 separate links to the same URI ( internally
they're separate links, but exposed as a single ).

This leads one to the issue of when parsing, identifying which rel is
"embedded" over merely "linked".

By clarifying, and making it explicit that an embedded resource has a
single reltype, a single "purpose" of why its being embedded, that'll
force my hand keeping track of the two - the embed rel being specific,
as opposed to being attached on a self link.

have sorted a couple of the issues you raised:

Cheers,
M

"Like the idea. One suggestion - the value at json._links.self will
often be a unique identifier. Maybe some provision can be made for
this to live at a top level, like json._id
There are strong arguments against that idea I'm sure, but consider
the boon to adoption you can get by having the only required thing be
a top-level element not a nested attribute."

I actually think that is not a bad point. What do people think about
moving _links.self to _self ?

Cheers,
M

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

One other thought - my api has a few calls that return a mix of
different types of result objects. I've been thinking the proper place to put
these would be in _embedded with a rel of maybe "results" or something.
If this is a reasonable use case (I think I saw somebody else on the list
mention it), then maybe that'd also be worth extracting up to the top
level and giving a well defined key?

- David

I'm on the fence on this right now, to be honest.

Cheers,
M

I can agree with keeping HAL as simple as possible. Is there a specific rel
that would be best practice to use if the resource is returning results in
_embedded? I'm probably going to want to build in some special handling
code for my HAL browser and I'd like it to be as generic as possible.

Cheers,
M

On Fri, Jun 8, 2012 at 4:42 PM, The Rabid Banana

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

- David

I actually don't like this suggestion because, as you noted below about
results, it can be a slippery slope.

I prefer the simplicity of the current specification and the fact that all
the links are collected in the same place, as are resources, and that the
top level has the resource's attributes.

Isn't this pretty much a return to what HAL -originally- had with _href
? Personally, if we were going back to this I'd rather see it return to
_href than _link as that keeps it inline with the XML spec.

I really think HAL needs a defined specification for making HTTP requests
to URLs with defined fields ("forms") before you submit it as an official
draft. It's a huge gaping hole in HAL right now, and it's just not useful
without it. It's like launching the WWW in the 90's with only links and
expecting someone to build on top of it later to have proper support for
actually *interacting* with websites and API endpoints instead of just
passively following links. Both linking and forms are keys to what drives
all interaction on the web, and you can't stop with just one - you have to
have both. JSONSchema provides some foundation for this, and although it
may not be perfect or ideal, it does allow the API to describe fields,
types, default values, etc. in a meaningful way. I propose that you should
at least provide a basic way of describing form URIs, HTTP methods, and
fields required for submission before creating an official draft.

Regards,
Vance Lucas

Please could you be specific about why it is you believe we must have
forms in HAL?

What benefits do forms bring in the context of machine consumed applications?

Cheers,
M

Really? Personally I don't think it should have ANY THING that ties it
-specifically- to HTTP at all.

In the one part of our system that's live that supports HAL we're going
HAL POSTed to the server along these lines.

On a resource, a link with rel "customer-import" points to
/api/createcustomer, the resolved documentation/spec for customer-import
tells you you that POSTing to /api/createcustomer with a HAL resource
can take the following "customer fields": firstName, lastName, address,
emailAddress.

As part of that resource, a number of embedded resources are also
supported for additional, transactional, related resources identified by
the rels: user-import, product-import.

An example document we can submit is ( in XML or JSON HAL ):

<resource href="/api/createcustomer">
   <firstName>Mark</firstName>
   <lastNme>Derricutt</lastName>
   <address>REDACTED</address>
   <emailAddress>exam...@mailinator.com</emailAddress>

   <resource rel="import-user" href="#user1">
     <username>markd</username>
   </resource>

   <resource rel="product-import" href="#product1">
     <code>SKU-0001</code>
     <quantity>32</quantity>
   </resource>
</resource>

In this example, the embedded href's are simply using fragment
identifies inside the master resource, and the resource URL is our
target endpoint.  These are just representations of what we, as a
consumer of the API want and don't reflect necessarily what the server
will actually create, or where they'll be created.

But it does conform to current HAL practices of keeping the requirements
of resource content in a resolvable rel.  This representation could be
FTP'd, SMTP'd, XMMP'd or transported by whatever other means you wish,
HAL in my mind is a _representation_ medium, not a transport itself and
should be kept independent if possible.

Mark

On 16/06/12 9:46 AM, Vance Lucas wrote:

Also, with currie - having the URITemplate variable "ref" point to
"name" seems to hurt my brain, reusing {{name}} in the template might be
better? Also, it should probably be noted that currie links don't HAVE
to be templates.

Mark

Practical use case: At work, our Rails frontend is just a client that
talks to our HAL API and renders it as HTML. Our version of HAL sends a
template schema that allows Rails to partially validate form input
before even talking to the API. It's obviously not guaranteed that all
clients of the api will validate input, or that the data will be valid
just because the schema said it was, but it does save clients willing to
take the validation step from having to do a round-trip that submits
data the server will obviously reject.

Having to read this information from the rel documentation is the exact
opposite of the advantage HAL provides - namely, allowing the server to
directly tell clients what they can do without extra, out-of-band
information. The templates sent as part of our HAL responses are built
directly from our validation rules, so they're kept in sync.

Another related use case is for debugging tools, such as a generic HAL
browser. Granting the ability to use and submit forms gives HAL
chance to provide a better developer experience. My Hal-browser fork
will (when I get the chance to add it) take advantage of the templates
returned by our API and show simple forms to make debugging new API
methods easier. Yes, you could just allow posting raw JSON and be done
with it, but I'd much rather let the server do a tiny bit more work
to give the end user a simpler experience.

Finally, for a resource that may change state, the presence or absence
of fields at different states could help a consuming application take
different action depending on that state. Maybe I can only update
certain fields on an order resource after the server has changed the
status to "shipping". Yes, this information can (and probably still
should) be conveyed in the rel documentation, but why should we ignore
the fact the server could easily tell us the valid fields when
we request that resource?

There are plenty of benefits forms can bring to HAL. I don't think they
should be required, but I don't think they can be ignored.

- David

Darrel

Maybe a good way to keep the spec lightweight while still allowing for the possibility of those who want forms or any other enhancements would be to just mention the capability of using "profile" rels in the same way microformats like hcard are used in HTML. Clients may use _links with rel "profile" to activate additional semantic meaning for certain attributes if the server provides one. I think this would be a great way to keep HAL extensible without adding much of anything to the actual spec - just specifying that profile rels can be respected by clients that choose to listen to them.

--
David