Re: Hydra compared with JSON API, other specifications

I think this is a great question.  Some of the responses I've seen have
been very heavily biased toward JSON-LD and Hydra (sometimes inaccurately),
but I suppose that's to be expected given the topic of the mailing list.  :)

The comparison of these media types is not very straightforward.  It's not
just a matter of listing features.  As with everything related to developer
experience, there's also a "look and feel" component.  And that's
undeniably subjective.  Even feature comparison, though seemingly
straightforward, can be nuanced.

Speaking in terms of "purity" leads down the path of sounding "too
academic" for many people.  (It's alienating.)  We've seen this for a long
time in the hypermedia community.  In the Web API / REST world, we've seen
this longstanding debate concerning what some people perceive as "purity
vs. pragmatism."  (For the record, I don't understand how these can be two
opposing forces.  It doesn't make sense.)

JSON API seems to have been an attempt to weave-in hypermedia using an
easily digestible format.  JSON-LD/Hydra has much more ambitious goals.  As
the number of features increase, the more difficult it becomes to manage
the flexibility-usability trade-off[1].

Before Hydra, Siren was perceived as being the most complex JSON-based
hypermedia format.  And now, I think, Hydra has taken over that label.  (I
see people move from Hydra to Siren to take advantage of reduced
complexity, which is a weird place for me to be in compared to the early
days.  I also promote Hydra when Siren lacks in a way that Hydra might
help.)

So based on my experience, here's what I can say:  If your goal is to
increase adoption of hypermedia within your organization, JSON API or HAL
will get you there quickly.  If you want to take full advantage of
hypermedia and effectively model complex interactions, such as workflows,
Siren or JSON-LD/Hydra can get you there.

There is often a progression that happens when people really get into
researching these formats.  I'm seeing more and more people land on Siren
as the preferred format each day.  I'm not as close to it, obviously, but I
have to imagine this is happening with Hydra at an equivalent or faster
pace.

I think we still have many years ahead of us before hypermedia achieves
widespread adoption.  In the meantime, the landscape is volatile.  You just
have to choose an option and jump in.  Either start with something simple
and evolve into a more feature-filled format or start with something that
seems a little more complex at first but will support your needs for the
long-term.  It's just a matter of choosing when to invest.  Not an easy
decision, for sure.  Good luck!

[1] https://en.wikipedia.org/wiki/Flexibility-usability_tradeoff

Cheers,

Kevin Swiber

On Mon, Jan 4, 2016 at 6:12 AM Paul Mackay <paul@folklabs.com> wrote:

> Hi,
>
> I’m iterating on a couple of API projects and have been reviewing the
> status of current API specification projects. JSON API (
> http://www.cerebris.com/blog/2015/06/04/jsonapi-1-0/) reached v1.0
> earlier this year and is more comprehensive than HAL (see
> http://jsonapi.org/faq/). I suspect Hydra could be even more flexible and
> comprehensive in terms of defining an API. However within the JSON API
> community that spec is being promoted as an anti-bikeshedding tool (avoid
> lots of debate about small issues) and yet getting to 1.0 involved a lot of
> bikeshedding!
>
> Has there been any comparisons between JSON API and Hydra, and what is
> behind the design choices of Hydra? I suppose a similar FAQ for Hydra along
> the lines of why it goes beyond other API framework specifications would be
> great :)
>
> Thanks
>
> Paul
>
>
> --
> Paul Mackay | 07761 050542 | www.folklabs.com
>