Document HTTP API request and response headers
- Dominant language
- Go
- Stars
- 30.1k
- Forks
- 4.6k
- Avg merge
- 1d 18h
- Merged PRs (30d)
- 39
Description
## 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`
Contributor guide
Research direction
Start by reviewing the HTTP API documentation and searching the source for X-Consul, header.Get(, and header.Set(. Create a central reference covering the listed request and response headers, choose an organization, and include curl guidance for setting request headers and inspecting responses; completion means the known headers are documented.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100