I'm currently working on a write-enabled addition to an API that is already somewhat hypermedia-esque. In particular, we return URLs instead of IDs. For the next version of the API, I'd like to start using custom or non-`application/json` media types. So I've been exploring HAL and collection+json. I am excited that this sort of thing is getting attention. It will help a lot of people building server-to-server and server-to-mobile applications once it's "a thing". I thought it might be useful to jot down the pros and cons, from my perspective, and share them with others who are designing hypermedia APIs. Both formats ------------ Pros: - Take a stab at providing a data model that makes clients a little-less boiler-platey HAL --- Pros: - Simple link format - Link templating for simple parameterized URLs Cons: - Underscore attributes (`_links`, `_embedded`, etc.) are obvious but feel ugly - Nothing specified for complex GET/POST parameters Collection+JSON ---------------- Pros: - Data model specifies GET query parameters and POST body parameters - Includes an error representation Cons: - More abstract data model; it feels like my data is shoe-horned in, rather than the C+J data model filling in the gaps in my data model - Nothing specified (at least on the examples page) about what HTTP method to use for writes Please to correct me if I'm mistaken on either of these drafts. In particular, I'm interested in learning more about how to explain these formats to client developers so they can build robust clients. More to the point, I'm trying to figure out how to explain hypermedia formats without getting into a hand-wavy posture implying that clients can magically upgrade themselves (not my kind of snake oil). Hope that helps anyone orienting themselves to designing on top of these data models! -- Adam Keys
Hey Adam- Thanks for sharing your write-up. One thing stuck out to me... > More abstract data model; it feels like my data is shoe-horned in, rather than the C+J data model filling in the gaps in my data model One of the interesting things about comparing the two is that HAL is 'domain agnostic' and Collection+JSON is 'domain... flavored.' I forget what word Mike uses, actually. Point is this: HAL is 100% generic, while C+J is designed to have a list of things and support filtering, searching, and doing things with that list. Maybe you were feeling is pain because you weren't naturally working with some kind of collection? > More to the point, I'm trying to figure out how to explain hypermedia formats without getting into a hand-wavy posture implying that clients can magically upgrade themselves (not my kind of snake oil). :) Does a 'service contract' sound better? In this style of API, the media type is the only real contract between the client and the server, built on top of the protocol. While it's not a contract in the WSDL style, exactly, it _is_ still the guideline. Maybe coming at the discussion from that angle would be a bit better.
On May 5, 2012, at 10:16 AM, Steve Klabnik <steve@steveklabnik.com> wrote: > > One of the interesting things about comparing the two is that HAL is > 'domain agnostic' and Collection+JSON is 'domain... flavored.' I > forget what word Mike uses, actually. Point is this: HAL is 100% > generic, while C+J is designed to have a list of things and support > filtering, searching, and doing things with that list. Maybe you were > feeling is pain because you weren't naturally working with some kind > of collection? I've found that it works best to model everything as a collection. But, I want that collection to look like it came from my domain. Atom and C+J have envelopes and envelopes before you arrive at domain data. Further, most examples get hand-wavy once you get to the actual data. That works in specs, but worked examples would help here, IMO. > :) Does a 'service contract' sound better? In this style of API, the > media type is the only real contract between the client and the > server, built on top of the protocol. While it's not a contract in the > WSDL style, exactly, it _is_ still the guideline. Maybe coming at the > discussion from that angle would be a bit better. A service contract is exactly what I want, love this framing. Has anyone experimented with writing these out in the style of an RFC?