Why we won't be using Collection+JSON

[Evert Pot]

Sorry for the dramatic subject. I tweeted this today:

> an issue I have with collection+json is that it's not really json-like. What HAL does well is that it augments simple objects

I had a bit of a discussion with Mike Amundsen after that, who asked me if I wanted to elaborate on this list.

I want to preface this with saying that I think Collection+JSON is very interesting. I've been watching it for a while, and I would enjoy building systems on top of it. I hope to find some use-cases in the future where it's appropriate.

Today my use-case is calendaring. For calendaring CalDAV is the most common standard. But CalDAV is based on WebDAV, and comes with a lot of cruft. While powerful, DAV doesn't really match what developers in 2015 expect from an API. I am a member of CalConnect, and from within that organization we are starting to look if we can build a new API for our abstract data-model.

A big goal if this new API would be to lower the barrier to entry to calendaring. For that reason we are looking at JSON.

In an attempt to do things 'right' this time, I managed to convince people to first just think about the 'mediatype', and ignore requests, urls, etc. We already have text/calendar to express events, and its companion jCal which is a direct mapping of iCalendar to JSON. It's likely that we recommend that the endpoints that are going to serve up individual events and todos will at least support iCalendar, and perhaps jCal.

What we have not decided yet, is how we are going to express a 'list of events'. 'A list of events' in CalDAV is a 'calendar collection resource' or the result of a search query. To get a list of events, the PROPFIND and REPORT http methods are used, and a WebDAV multistatus XML response is returned along with a 207 status code.

We need to replace this, but it would also be nice to not have to reinvent the wheel. So I've looked at HAL, Collection+JSON, JSON-API, SIREN, XRD/JRD and JSON-LD.
The main features I am looking for are:

1. A standard way to express link relationships.
   
2. A standard way to express a collection of resources (with some information about these resources)

The reason I rejected Collection+JSON is for two reasons:

1. It's not aesthetically pleasing.
2. Data values can not be objects, they must be expressed as linked collection resources.

I don't think I need to elaborate on #2, but I will explain why #1 is important:

The benefit that HAL (and others) have, is that they augment simple json objects. This means that for all the people that don't care about HATEAOS, they can still use the a json endpoint in this way: (PHP example)

$obj = json_decode(file_get_contents('http://some/event.ics'));
echo $obj->dtstart; // shows start time

Now you might consider this a weak technical argument, and it is. Mike says:

     "yes. that was by design. Cj is not code, it's *msg*. just as HTML relies on DOM for programming, Cj has a DOM, too."

I agree with Mike. With a good Cj client my code sample could still be a 2-liner. How the information is transmitted over the wire shouldn't matter. It should be an implementation detail, and the message on the wire should be the most effective expression of the data-model it represents.

But I feel that the reality is that people do care how it looks. The reason why formats such as HAL exist, is because people *want* to work with plain json objects. This is an important factor for me. I want to build an API that people *want* to use, and as a result we might go with a mediatype that's closer to "idiomatic JSON apis", trading in the technical benefits that Cj would  otherwise provide.

The other reason is that I do not believe I can get people on board. If even I personally felt that Cj is the better choice, I am not going to be able to convince the rest of members of the working group. Suggesting using any standard media-type was already a battle and so was convincing people to use URIs for identifiers. Cj will be perceived as not being able to meet one of our main goals: to lower the barrier of entry to calendaring APIs.

So... this is my line of thinking. I hope this is useful and not discouraging. I want to live in a world where formats such as Collection+JSON are the both the standard and the popular choice, then this trade-off will not have to be made.

Evert

[mca]

First, thanks for posting here. Lots of interesting items in this msg..

1) i totally understand that Cj is not a good fit for CalDAV. Since Cj has no direct way to communicate HTTP Methods (PROPFIND, MGET, etc.), you'd need to create an extension for the CalDAV support and that extension would be ignored by generic clients.

2) If Cj is rejected because of our aesthetics, there's not much to be done there. I appreciate that you want to select media types that match your personal tastes. I assume HTML *is* pleasing to you?

3) As for supporting data objects, you're spot on. Cj was designed to NOT do that and if that is a requirement for you, you could use one of the existing extensions, but (as above) will be foregoing generic client support again.

4) as for "people DO care how it looks" I'll just assume you are not trying to say that *I* NO'T care how it looks. I suspect you mean that you don't like how Cj looks. You might even mean that you think some/many/most of your target developer audience don't like how it looks. I really can't comment on that other than to say (as I mentioned above) that if looks are a basis for rejection, and you don't like Cj's looks, there's nothing to be done for that.

5) I also understand that getting teams to adopt standards other than HTML, CSS, & JS can be tough. Not sure how you plan to change that. It's possible that adopting a new standard that just looks like one of the old ones will help you get ppl on board. Again, Cj is not going to help you if you'be got ppl who don't want to adopt a new format.

Finally, I'd like to see what format you finally do choose and learn more about why that choice was made. I'll especially be interested in the features of your ultimate choice that made the cut. the aesthetically pleasing elements that tipped the scale for you and your audience.

Thanks again for offering your observations here and please keep me posted on how this works our for you. I can learn more from how you end up solving your format/API design challenge.

Cheers.

 

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

--
You received this message because you are subscribed to the Google Groups "Collection+JSON" group.
To unsubscribe from this group and stop receiving emails from it, send an email to collectionjso...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[John Lim]

"But I feel that the reality is that people do care how it looks. The reason why formats such as HAL exist, is because people *want* to work with plain json objects. This is an important factor for me. I want to build an API that people *want* to use, and as a result we might go with a mediatype that's closer to "idiomatic JSON apis", trading in the technical benefits that Cj would  otherwise provide"

------

I'm facing a similar situation at work. For some reason, a number of people are more comfortable with "pure" json objects. Although over-simplifying it, some prefer to .date directly rather than .collection.items.data etc. with the reason being it is more readable. For me that sounds more like coupling.

In my case, I think it boils down to a general lack of awareness and knowledge on REST, Hypermedia and of course CJ. Getting the product to transition to REST, then hypermedia is already a great challenge and sadly, the choice of which hypermedia format to use is probably less important in this case. I think hypermedia formats like CJ are the way to go. Just think of USB and how its "format" allows clients to "learn" about the devices and enumerate them correctly. Its not readable (to the layman) but enabled interconnectivity unlike any other before its time. 

I think the key to adopting CJ is to lower the barrier to entry. By that I mean we will need tools and libraries that we can use off the shelf so that Cj can be adopted easily.

Just my 2 cents worth.

Cheers.