Sam Johnston <samj@samj.net> writes:

> These are both valid alternatives but given our ultimate aim is to reduce
> costs it makes [a lot] more sense to have a primary format which supports
> mechanical transforms than to externalise the development to implementors
> (and then expect the results to be interoperable).

Something implicit here is worth highlighting: this route only leads to
interoperability if the extra formats are mandatory, not if they're
optional.

No, this route leads to interoperability provided at least one format is mandatory. I don't rate myself enough to say which alternative formats will be most useful today, let alone tomorrow, so if the number of required formats exceeds 1 (it need not IMO) then it should be no more than 2 or 3 and we should make life as easy as possible for implementors (think transforms).

Otherwise, I can write an OCCI-compliant tool in bash which talks KEY VALUE
text, but it won't be able to connect to Richard's front-end (which only
understands JSON) or use another provider's front-end (which only
understands Atom).

Right, obviously at least one format needs to be mandated and that format should obviously be as widely supported and easily translated to others as possible. Simplicity, while important, is secondary IMO - oversimplifying has the same result as overcomplicating.

The option of making one format mandatory and the others optional won't fly,
because in that case the only way you write code that's guaranteed to work
is to use the mandatory format, whereupon you've effectively converged on a
single rendering in all but name.

...so we should just converge on a single rendering and be done with it? There is absolutely value in convenience formats, as evidenced by Google's JSON renderer... without them we wouldn't be able to do things like setup cron jobs to run regular tasks or write scripts to automate routine tasks such as failover.

Quoting your own insightful "Designing a great HTTP API" post from earlier in the year (because I couldn't have said it better or clearer myself):

Simple syntax means making it easy for any user with a standard tool to call the API. If you can’t call the API with curl from a single line of shell then your API is not good enough. This rules out many of today’s cumbersome XML-RPC and SOAP APIs, although you will want XML as an option for users who are using XML-friendly languages.

We believe in:

Choice of syntax: Different users will find different syntax most natural. At the unix shell, space-deliminated text rules. >From Javascript, you’ll want JSON. From Java, you may want XML. Some tools parse x-www-form-encoded data nicely. A great HTTP API makes every command available with data in all of these formats for all of these users, specified with either different URLs or MIME content types. (OK, we admit that we’ve only released text/plain ourselves so far, but the rest are coming very soon!).

Don’t reinvent the wheel: Smart people designed the internet. There are good existing mechanisms for security (e.g. SSL/TLS), authentication (e.g. HTTP auth), error codes (e.g. HTTP status codes), etc. Use them, and don’t invent your own, unlike one UK payment gateway who invented a simple XOR encryption which is vulnerable to a known plaintext attack and didn’t fix it when we pointed this out!

Sam