14

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"?

Matthew Woo
  • 1,288
  • 15
  • 28

1 Answers1

6

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):

Considering the question relates to the difference when used as Content-Type1 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.

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

Pierre B.
  • 11,612
  • 1
  • 37
  • 58
  • 1
    Interestingly there are 2 aws api gws my project calls, one of them accepts `application/x-amz-json-1.0` (I didn't try others), while another **requires** `application/json` and fails with `x-amz...` – Dima Tisnek Oct 25 '21 at 06:53
  • 1
    "required for POST" bit is so easy to misread... I though that Pierre meant that `x-amz...` is required when issuing POST requests against the API GW; while in fact (?) it's only that the `Content-Type` request header field is required for requests that have a body (PATCH/PUT/POST), while the value of the field is not mandated. – Dima Tisnek Oct 25 '21 at 06:58
  • 1
    You're not wrong, I reformulated to clarify this. – Pierre B. Oct 25 '21 at 14:10