Introduction
This is my own personal notes on what I've found out on the web for beginning to consider hypermedia approaches for linking data. I've relied on the wider community for their advice and findings and so I hope others will find this page a handy one stop shop.
Acknowledgements
Taken from Niels Krijge Blog
So grateful that somebody has already done a comparison. Legend can be found here
| Hypermedia Type | Primary keywords | Embedded resources | Single object wrapper | Documentation links | Pagination | Sorting | Error | Partial updates | Query | Actions | Partial result | Matches vanilla |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| JSON:API | id, links, meta, linked, type, href | Yes | In array | No | No | Yes | Yes | PATCH | No | No | Yes | 3/5 |
| HAL | _links, _embedded, curies | Yes | No | Yes | Minimal | No | No | No | No | No | No | 4/5 |
| Collection+JSON | links, collection, items, href, data, queries, template, version, error | No | In array | No | No | No | Yes | Write representations | Yes | No | Yes | 2/5 |
| Siren | class, properties, entities, links, actions, title, rel, href, type | Yes | In properties | No | Minimal | No | No | No | Yes | Yes | No | 2/5 |
| JSON+LD | @context, @id, @value, @language, @type, @container, @list, @graph ... | No | No | No | No | No | No | No | No | No | No | 3/5 |
JSON API
Taken from Mike Stowes blog.
Strengths
- simple versatile format
- easy to read / implement
- wide adoption
- strong community
- recognized as IANA media type
- designed to be less chatty "without compromising readability, flexibility and discoverability"
- backward compatibile
- lots and lots of implementations in a variety of languages
Weaknesses
- forces you to identify resources with the reserved keyword 'id' so limits more advanced uses cases of compound keys
- JSON only
- still WIP
- no documentation links - whether the hypermedia type specifies how to access human readable documentation of a resource.
HAL
Strengths
- dynamic - what does this mean? does this mean data inclded in the response to describe an object
- nestable
- easy to read / implement
- multi-format - XML / JSON
- URL templating
- inclusion of documentation links - HAL is the only one to support this
- wide adoption
- strong community
- recognized as a standard
- RFC proposed
Weaknesses
- JSON/XML formats architecturally different
- CURIEs are tightly coupled
JSON-LD
Strengths
- strong format for data linking
- can be used across multiple data formats (Web API & Databases) ? huh?
- strong community
- large working group
- recognized W3C standard
- JSON-y so client devs will find it familar
- can add actions to it with Hydra (still WIP)
- SPARQL support
Weaknesses
- JSON only - how to get around this?
- more complex to integrate
- no identifier for documentation - how to do this?
- limited support for pagination, sorting, error, partial updates, query, actions etc