CODEWITHSUNDEEP
resthttphttp-headers
Lone Wanderer
Lone Wanderer

Reputation: 198

Naming convention behind HTTP headers

I'm building an API and I need to trace the message as it goes trough my systems. For this purpose, I'm planning to use X-Correlation-Id HTTP header, but here I have an into problems.

First, the X- prefix is deprecated and its use discouraged. That would leave me with Correlation-Id.

Second, I'm intending to use hyphens, but as I'm reading https://www.rfc-editor.org/rfc/rfc7230 I realize that hyphen isn't named anywhere explicitly. section-3.2.6 Mentions excluded characters - those are the characters unsusable for http header delimeters?

Third, since the HTTP headers are case-insensitive, should I define all of my expected headers in lower case? I'm asking because the more research I do, the more variations on this I find. Some APIs have capitalized headers, some dont. Some use hyphens and some use underscores.

Are there unambiguous guidelines for this stuff? I'm telling my boss that using camelcase for HTTP headers is not optimal but I cant find any guidelines for this.

Upvotes: 3

Views: 10015

Answers (2)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57327

RFC 2822 defines the production rules for Headers

A field name MUST be composed of printable US-ASCII characters (i.e., characters that have values between 33 and 126, inclusive), except colon.

You'll find an ABNF representation in the section that describes optional fields

optional-field  =       field-name ":" unstructured CRLF

field-name      =       1*ftext

ftext           =       %d33-57 /               ; Any character except
                        %d59-126                ;  controls, SP, and
                                                ;  ":".

In HTTP specifically, you'll want to be paying attention to the production rules defined in Appendix B (note that HYPHEN-MINUS is a permitted tchar)

field-name = token

header-field = field-name ":" OWS field-value OWS

tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
    "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA

token = 1*tchar

If you review the IANA Message Headers Registry, you'll find quite a few headers that include hyphens in the spelling. Careful examination will show a number of standard HTTP headers that include hyphens (Accept-Language, Content-Type, etc).

Third, since the HTTP headers are case-insensitive, should I define all of my expected headers in lower case?

For your specification, I would recommend spelling conventions consistent with the entries in the IANA registry; in your implementation, you would use a case insensitive match of the specified spelling.

Upvotes: 1

Julian Reschke
Julian Reschke

Reputation: 42065

  1. As long the use is private, the field name does not matter a lot. In doubt, use "application name" instead of "X".

  2. Field names are use the "token" ABNF, and that does include "-".

  3. As they are case-insensitive, it doesn't matter how you "define" them. In doubt, use the same convention as the HTTP spec. CamelCase in particular is not helpful, as HTTP/2 (and 3) lowercase everything on the wire.

Upvotes: 3

Related Questions