1) Yes there’s better ways of handling multi lang (I would go for the Accept-Language / Content-Language HTTP headers in an API response like this – your suggestion of using the URI is fairly common in websites too (but using the preferred language setting in the browser included in the header I think is cleaner). The language example above was only really to show where JSON ends up being changed quite a lot, and XML stays almost the same in structure.

2) I’m not sure I agree. If you gzip your response (and you should) you’re going to get down to a fairly comparable size whether it’s JSON or XML. Do agree that for multi lang though, the decision of what language to present *should* happen on the server, rather than in the client.

3) Depends. For simple structures, not really. When you start getting more complicated (arrays of objects in arrays etc) the fact that XML is just a more expressive format means that you have fewer lines to traverse, so it can actually make it easier to understand.

1) Re multilingual APIs. One option is to simply make the lang part of the URI (eg app.com/api/en/users/1 and app.com/api/de/users/1). I would argue that this could be a better design – coming from Symfony2 background where it encourages us to make the locale part of te URI.

2) I think in many cases JSON will result in smaller responses which is important when bandwidth is a concern. Also, by doing 1), you reduce the response size too.

3) Personally I actually think JSON is easier to read. Do you really think the XML is easier?

Cheers, Jon

{
    "error": {
        "id": 6,
        "message": "Something bad happened",
        "message_de": "Something bad happened (in German)"
    }
}

Doesn’t force any old clients to update anything either. New users can just suffix the language code to the field(s) that is/are translated.
I’m pretty sure most people can live with the fact that the primary language (en) of the JSON is omitted since English is pretty much the defacto standard for any API.

My other two pet peeves with JSON are: 1) that it is (unnecessarily) difficult to validate, especially when compared to XML, and 2) that (for PHP, anyway) there is a distinct lack of stream parsers available for it.

Obviously, these so-called problems are easily solved by not validating your API I/O and just increasing the memory limit for your PHP processes…

“It probably isn’t.”

Especially not if you’re using Java! :P

I’m tempted to back out that facility in JSON to remove complexity from the format and just leave it as an option in the XML representation (and primarily use con-neg for it).

My thinking behind having it is incase the server blows up (5xx response) before the con-neg has complete – but perhaps it’s over thinking it.

Regarding the recent addition of multiple languages within the response, why not handle that via content negotiation on Accept-Language, etc.?

The vnd namespace is a lot more relaxed on the peer review aspect of getting the mime type approved. It’s not been discussed on the ietf-types mailing list (but i’ll drop a post in there). The spec is in draft form, and there are several changes and enhancements on the way already. If you have any suggestions then please do let me know.