What is "application/x-amz-json" and how is it different from "application/json"?

Question

I've run into "application/x-amz-json-1.1" in making requests to AWS resources. Most recently, it became a problem that an API Gateway I was communicating with didn't like handling it (for whatever reason). This got me wondering what the benefit to using application/x-amz-json-1.1 instead of application/json for my requests is. And to my disappointment, AWS doesn't seem to have any documentation on this odd content type.

So I turn to SO: what is "application/x-amz-json" and how is it different from "application/json"?

Answer 1

Amazon does not specifically document what application/x-amz-json Content-Type is for, however there are protocol documentations on Smithy (an open source language for defining services and SDKs published by AWS):

• AWS JSON 1.1 protocol
• AWS JSON 1.0 protocol

Considering the question relates to the difference when used as Content-Type¹ header to make requests, I think we can tell the difference is:

• application/json is to request/receive JSON data without anything more specific
• application/x-amz-json-1.1 (or other version) is also to request/receive JSON data and expect additional behaviors described in the docs above. (i.e. tell the server/client this is JSON plus additional elements)

I think application/x-amz-json can be thought as a sort of extension or a more specific way of doing application/json requests.

it became a problem that an API Gateway I was communicating with didn't like handling it (for whatever reason)

In the specific case of making PATCH, PUT and POST requests to AWS Amazon API Gateway, specifying Content-Type header application/x-amz-json-1.1 or other version seems to be required. As per related docs:

Content-Type (Conditional)

Specifies JSON and the version, for example, Content-Type: application/x-amz-json-1.0.

Condition: Required for PATCH, PUT and POST requests.

Maybe the server understands application/json as basic JSON but requires application/x-amz-json-1.1 to perform specific requests.

---

¹Content-Tye header being used to tell the server/client how to process our request