Specify content-type properly in REST APIs

[ali-jalaal]

What is the underlying problem you're trying to solve?

It seems content-type request header in REST APIs is not well-documented and documentations could become more clear. Some APIs do not mention content-type request header and some of them do not specify all possible options.

Describe the ideal solution

Ideally all REST APIs could be reviewed to:

• add missing headers
• specify required/optional request headers and query parameters

Describe a "Good Enough" solution

1. Missing application/json content-type headers
The following APIs:

• Get a Document (with Input)
• Get a Document (Webhook)
• Execute a Simple Query

specified in the Request Headers section:

Content-Type: application/yaml: Indicates the request body is a YAML encoded object.

This description could be misleading, since:

• application/json content-type is not mentioned
• almost all examples in this page are based on JSON

This could be improved by specifying application/json as a valid content-type.

2. Missing headers
The following APIs:

• Create or Update a Document
• Patch a Document
• Execute an Ad-hoc Query - with Post
• Partially Evaluate a Query
  accept request body, while did not mention content-type header.
  Moreover, regarding gzip headers (Content-Encoding: gzip & Accept-Encoding: gzip), only Partially Evaluate a Query mentioned them, while they could be applicable for other requests.
  If some headers (e.g. gzip headers) are common for all requests with body, they could be specified at the beginning of the document and then reference to them in the related APIs.

Additional Context

[anderseknert]

Thanks! We'd be more than happy to get some help with this, if someone wants to step up to the challenge 🙂

[ali-jalaal]

I'll try to work on that. 🙂