Document HTTP API request and response headers

[jkirschner-hashicorp]

Problem

It's difficult to understand how to use headers in the HTTP API because:

• Some headers aren't documented anywhere (e.g., X-Consul-Partition)
• If looking at a response, it can be difficult to quickly understand what the included headers are for (without a lot of searching through the docs

Proposal

Create a central reference document for all request and response headers. The organizational hierarchy of such a page needs to be thought through. Options include:

• Level 1: request or response header. Level 2: category (e.g., auth vs debug)
• Level 1: category. Level 2: request or response header.
• There may be other relevant options

Ideally, this page would also include a section describing how to set request headers and inspect response headers (e.g., curl example).

Known headers to document

Header lists populated below were generated by (case-insensitive) searching through the source code for matches to:

• X-Consul
• header.Get(
• header.Set(

Request headers

• X-Consul-Token
• X-Consul-Namespace
• X-Consul-Partition
• X-Consul-Datacenter
• Authorization
• Cache-Control
• X-Forwarded-For
• Accept
• User-Agent
• Content-Type

Response headers

• X-Consul-Results-Filtered-By-ACLs
• X-Consul-Effective-Consistency
• X-Consul-Index
• X-Consul-Translate-Addresses
• X-Consul-ContentHash
• X-Consul-Query-Backend
• X-Consul-Reason
• X-Consul-KnownLeader
• X-Consul-Default-ACL-Policy
• X-Consul-LastContact
• Content-Type
• X-Cache
• Age

[blake]

Is the goal here to document standard HTTP headers in addition to Consul-specific headers?

[jkirschner-hashicorp]

My opinion is that it would be to document:

• Consul-specific headers
• Any standard headers that Consul uses or generates in ways that aren't necessarily obvious

The list above may include headers that we don't really need to document. I was focused on quickly capturing what I could find in our source code so someone could downselect later. I didn't want to prematurely downselect.