hashicorp / hashicorp/consul

Document HTTP API request and response headers

Open
#12,544 2 comments 3 reactions 0 assignees View on GitHub
theme/api type/docs
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.