Naming convention behind HTTP headers

Question

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.

Julian Reschke · Accepted Answer · 2025-04-15 14:50:44Z

3

As long the use is private, the field name does not matter a lot. In doubt, use "application name" instead of "X".
Field names use the "token" ABNF, and that does include "-".
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.

edited Apr 15 at 14:50

answered Jan 26, 2021 at 15:47

Julian Reschke

42.5k8 gold badges103 silver badges101 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

user1007074 Mar 31 at 10:13

Beware of the ambiguity between camelCase and UpperCamelCase. Use PascalCase if you definitely mean for the first letter to be upper case

Community · Accepted Answer · 2021-10-07 11:32:16Z

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.

Collectives™ on Stack Overflow

Naming convention behind HTTP headers

2 Answers 2

1 Comment

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

1 Comment

Comments

Your Answer

Sign up or log in

Post as a guest

Related