Month: April 2012

JSON Sucks

April 26, 2012 Uncategorized 15 comments , ,

Ok, so perhaps I was a little bit OTT with the title of this blog post (but it got your attention, right?). What I actually mean is that JSON Sucks for hypermedia APIs, and I am going to tell you why. But before I do, I just want to point out that actually I think JSON is awesome for what it’s designed for – serialising an object. Objects naturally contain data structures like ints, strings, arrays and other objects – if all you need to do is represent those four things, you can’t go wrong with JSON. Seriously.

Hating XML is rather fashionable these days, so many API’s are appearing that are JSON representation only even when XML really is a better fit for purpose. When you’re designing a hypermedia API you’re not simply serialising an object. There are media types that add semantic meaning to JSON (application/hal+json, my own application/vnd.error+json (draft) and others) but really, XML is so much more expressive that using JSON actually makes your clients have to work harder to understand the meaning you’re trying to convey using an object serialisation format over a markup language.

XML gives you some stuff for free – ‘xml:lang’ for one. Put this on any element of your document and just the fact that your document is XML means that you can express elements in different (human) languages without having to update your media type.

Consider how this actually looks in XML vs JSON representation.

<error id="6">
    <message>Something bad happened</message>
</error>
{
    "error": {
        "id": 6,
        "message": "Something bad happened"
    }
}

This looks easy, right? Consider a future version of the api where we add support for multiple languages.

<error id="6" xml:lang="en">
    <message>Something bad happened</message>
    <message xml:lang="de">Etwas schlimmes ist passiert</message>
</error>
{
    "id": 6,
    "messages": [
        { "lang": "en", "message": "Something bad happened" }
        { "lang": "de", "message": "Etwas schlimmes ist passiert" }
    ]
}

An alternative could be to key the message objects by language;

{
    "id": 6,
    "messages": { 
        "en": "Something bad happened",
        "de": "Etwas schlimmes ist passiert"
    }
}

You can see in both scenarios that “messages” has become an different type (string to array of objects, or string to object). We’ve changed the structure of the document and introduced an almost certain backwards compatibility (BC) break in our interface – all our clients now need to be updates to follow suit. We could leave “message” as it was, and add “messages” for the multilang version of the API but then we’re duplicating data and / or making the client have to work harder.

The XML version can continue as is and the client can simply ignore the additional languages until they’re updated to support them (if they ever need to).

Then there’s just the matter of basic human readability. It’s clear to see what’s going on in XML and not so much in JSON. This is a fairly simplistic example but extrapolate that out over a fairly complex representation of an object and you can see how JSON really isn’t always the best choice for representing resources.

Imagine the scenario where we had used the second option above as our JSON representation and we wanted to add in another attribute for each of the messages. See the problem? Anything we choose to do will cause a BC break and require clients to update (or result in duplication of elements to ‘version’ the api), meaning it’s very difficult to evolve the clients and servers independently.

So i’m not saying that JSON simply ‘sucks’. I’m just saying that when considering the formats you use for representing data in an API (when it comes to selecting the media type you want to use), think hard before just going with something based on JSON by default because it’s ‘easy’. It probably isn’t.

The error hypermedia type

April 24, 2012 Uncategorized 5 comments , ,

When designing a complex hypermedia API you will inevitably come across the situation where instead of returning the required resource, you need to return an error state. Currently, there is no hypermedia type registered with IANA to deal with this scenario, so it is left up to the API designer to construct and document a mime type that can be used to express an error state in the application.

Because of this, several people have come together and put together a proposal for the application/vnd.error media type. It has been documented over on Github and the mime type has been submitted for approval by IANA.

The intention for this media type is that it should be used when a client has made a request, however the server is unable to fulfil the request to to either a server side error (a code 5xx) or a problem with the client request (a code 4xx).

Although the client does NOT have to state that it explicitly will accept the application/vnd.error+xml or json mime type (via the ‘Accept’ header in the request), it makes a lot of sense to do so if the client can understand that response type. However, RFC2616 section 10 states:

HTTP/1.1 servers are allowed to return responses which are not acceptable according to the accept headers sent in the request. In some cases, this may even be preferable to sending a 406 response. User agents are encouraged to inspect the headers of an incoming response to determine if it is acceptable.

It is up to the implementor to decide whether the api should return a 406 (Not Acceptable) response if the client states it will not accept application/vnd.error+xml or json and an error is triggere, or if it should return the application/vnd.error+xml or json response anyway.

The specification for application/vnd.error is draft – if you have comments / suggestions or enhancements to the media type, let’s talk (comments on this blog, issues on github, twitter etc).

PHP 5.4 web server

April 11, 2012 Uncategorized No comments

For me, one of the most exciting things that we have in PHP 5.4 is its built in web server. It makes being able to jump in the deep end with new ideas much easier and avoids the tedious work in setting up and needing apache to run before you have code to deploy. I have been playing around with the Silex framework in the last few weeks to build a prototype of a REST API that I have been thinking about. This is how I got going with Silex once I had PHP 5.4 installed.


wget http://silex.sensiolabs.org/get/silex.phar
php -S localhost:8080

Create an index.php in the current directory (there’s an example app on the Silex home page). That’s it. Go play. :)

Code review Karma

April 9, 2012 Uncategorized 1 comment

Implementing a good code review system into a development process is something that I have found quite difficult to do. The idea of it is conceptually quite simple – just make sure that before code is accepted into the main development stream that it’s reviewed by someone before being allowed to pass. Tools like github compliment git really well but force you down a development path that really suits open source software development, but not necessarily a co-located team.

My problem is that I trust my developers to do the right thing. Ok, so that’s not a problem – it’s actually a really nice place to be. I see code review as a learning exercise for good developers, but I don’t see is as a blocking part of the development cycle. Too many times I have seen code reviews as a blocking step in a software release cycle end up just being a formality to get through.

With that scene set i’ve been thinking of using a karma based code review system. Developers have karma (per project) and can give out positive and negative karma to other developers. At a certain level of karma, the number of reviews required on commits starts to drop off so that eventually a commit by a developer with high karma will not generate a code review (or the percentage of commits submitted for review will be very low). As a project progresses, hopefully this leads to a place where developers who will learn more from having reviews done will have the benefit, while the developers who are well established on the project are able to get code into the project repository without a blocking code review process. Improvement can be measured by karma increasing over time.

Do you have experience with code reviews on projects? (open source vs closed source / colo teams vs non-colo / blocking vs non blocking)… Interested to hear others success and failure stories!