About a few weeks back, Amazon SWF started validating the content type of the incoming request. As a result, a my-until-then-working-application started failing with this exception:

{\”__type\”:\”com.amazon.coral.service#UnknownOperationException\”,\”message\”:null},\”Version\”:\”1.0\”}”

To get past the error, I had to set the contentType to  ‘application/x-amz-json-1.0’ instead of ‘application/json’.

Not a big deal (just a few hours of troubleshooting) until I put my REST glasses on (note: neither amazon swf nor I are claiming that amazon swf is REST compliant) .  This incident did give me a chance to stop and ponder over API design in general and REST API design in particular. The spirit of REST compliant architecture is to enable independent evolvability of resources (like Amazon SWF) and consumers (my application).  I believe these are a few points to bear in mind:

Describe your representation (mimeType)

Representations are the medium using which consumers modify a resource. Hence, if you roll a custom mimeType, it is your responsibility to provide a detailed definition of it, like application/json, or text/vcard.

Amazon did not do that with ‘application/x-amz-json-1.0’.  Currently, i am not sure what it is. You and I can guess what is, but that is not how things should be.

Further, REST does not specify where your custom representation definition should be stored. You could create your own “well known” location, like IANA, where your consumers can look it up.

Don’t “alias” existing mimeTypes

REST is all about relying on standards, on the premise that it will reduce dependency. If there is an existing standard that fits your needs, like application/json, then use it. It is not being responsible to roll out a mimeType that is exactly like an existing one. It appears that you might be hedging against changes to json or preparing to roll your own. In either case, your are guaranteed to break your client in future, because your client and you are not working of the same standard.

Roll your own mimeType, only when it has something special to offer. mimeTypes/representations (reading/writing) are “generic” skills that your client needs to master. For example, browsers need to know how to render ‘text/html’, ‘image/jpeg‘ and so on and so forth.

Preserve backward compatibility

This is the most obvious one. Find a way to keep your client up and running, especially for such seemingly superficial change like replacing ‘application/json’ with ‘application/x-amz-json-1.0”