Are HTTP headers case-sensitive?

Question

In a blog post I use the following PHP to set the content-type of a response:

header('content-type: application/json; charset=utf-8');

I just got a comment on that post saying that content-type needs to be capitalized, Content-type. Is this correct? It seems to work for me with all lower-case, and I assumed the HTTP headers were case-insensitive. Or does it just work because browsers are nice?

Boar

It's case insensitive, but if you're going to fix the case, it should be 'Content-Type'. – Euchologion

FWIW, sending "charset" with application/json is pointless. There is no such parameter. – Artair

@JulianReschke There are no downsides to adding the parameter. Also, there are even some applications/libraries that will flat out not work unless it includes a charset parameter. Applications that don't expect a charset parameter on the other hand will continue to work fine if you add it. – Ronironica

@Ronironica - the downside (aside from wasted bytes) is to continue to confuse people about the charset param. Just get those components fixed instead. – Artair

@JulianReschke is correct. The IANA application/json assignment says charset is meaningless for this media type. it doesn't do anything. Please don't add it, because it's noise that leads to unnecessary confusion. – Badge

Could charset inclusion be future-proofing? Let's assume you've got internationalised templates in your json ... charset=utf-16 / 32 ? – Erasure

I’d guess probably not, Tyeth. JSON is specified as being encoded in UTF-8, UTF-16 or UTF-32 only; anything else, and it’s not JSON. Those are encodings, not character sets (though "charset" is fuzzy about this distinction) — they are all encodings for the same character set, that of Unicode. The spec also mandates the algorithm for determining the correct encoding from the content alone, so the only reason one might include this is to work around bugs in software that both reads JSON and content type headers incorrectly. – Cruz

Answer 1

Header names are not case sensitive.

From RFC 2616 - "Hypertext Transfer Protocol -- HTTP/1.1", Section 4.2, "Message Headers":

Each header field consists of a name followed by a colon (":") and the field value. Field names are case-insensitive.

The updating RFC 7230 does not list any changes from RFC 2616 at this part.

Landside

Answer is still true, RFC 7230 states: "Each header field consists of a case-insensitive field name followed by a colon (":"), optional leading whitespace, the field value, and optional trailing whitespace." – Lycia

Header fields are case sensitive when using PHP to get the value of a header field using the method 'apache_request_headers()'. – Teel

Can anyone provide examples of popular browsers that do not comply with the spec in this regard? – Thibault

@Teel That's only because string comparison in PHP is case-sensitive. – Clearsighted

For anyone looking, here is where RFC 7230 explicitly states that field headers should be treated as case insensitive: tools.ietf.org/html/rfc7230#section-3.2 – Anemic

Random fact: some systems (AWS CloudFront being one) may leverage this part of the standard when they rewrite your headers. I've had the case of header keys change on me unexpectedly - good to know for next time – Ac

what about header field values? – Benenson

@JoeCodeFrog: Header field values are application-defined; you will need to consult the documentation of the specific application in use. – Landside

Am I the only one who think that "case-insensitive" does not mean that case can nor should manipulated? – Cottrill

@MatteoSp, I think that's probably a yes. – Erotomania

@Ac I just had this experience – Heyerdahl

Answer 2

HTTP header names are case-insensitive, according to RFC 2616:

4.2:

Each header field consists of a name followed by a colon (":") and the field value. Field names are case-insensitive.

(Field values may or may not be case-sensitive.)

If you trust the major browsers to abide by this, you're all set.

---

BTW, unlike most of HTTP, methods (verbs) are case sensitive:

5.1.1 Method

The Method token indicates the method to be performed on the
resource identified by the Request-URI. The method is case-sensitive.

   Method         = "OPTIONS"                ; Section 9.2
                  | "GET"                    ; Section 9.3
                  | "HEAD"                   ; Section 9.4
                  | "POST"                   ; Section 9.5
                  | "PUT"                    ; Section 9.6
                  | "DELETE"                 ; Section 9.7
                  | "TRACE"                  ; Section 9.8
                  | "CONNECT"                ; Section 9.9
                  | extension-method
   extension-method = token

Nalepka

Another comment said this answer is obsoleted. Is that true? If so, maybe you can update it so people don't get confused. – Plains

using curl -X put lower cased verb will return 400 bad request cryptic error from server. It took some time before realizing that verb was invalid. curl also did not throw any warnings. curl -X PUT went thru. – Aldin

Answer 3

tldr; both HTTP/1.1 and HTTP/2 header names are case-insensitive BUT HTTP/2 enforces lowercase header names.

HTTP/1.1

According to RFC 7230, section 3.2:

Each header field consists of a case-insensitive field name followed by a colon (":"), optional leading whitespace, the field value, and optional trailing whitespace.

HTTP/2.0

Quoting RFC 7540, section 8.1.2:

Just as in HTTP/1.x, header field names are strings of ASCII
characters that are compared in a case-insensitive fashion.

...but then:

However, header field names MUST be converted to lowercase prior to their encoding in HTTP/2. A request or response containing uppercase header field names MUST be treated as malformed.

Collegium

just clarifying: field names are case insensitive; field values can be case-sensitive, depending on the field name. – Artair

Continued citation from HTTP/2 RFC: "However, header field names MUST be converted to lowercase prior to their encoding in HTTP/2. A request or response containing uppercase header field names MUST be treated as malformed (Section 8.1.2.6)" – Consort

I just noticed the "MUST be converted to lowercase..." part as well. Why is that? CamelCase appears to be preferred casing in practice (developer tools, popular code libraries), so why would HTTP/2 attempt to go against that trend? – Stadiometer

@Stadiometer - because standards are about consistency - using camel-case can be ambiguous - especially with abbreviations, initialisations and acronyms. For example - would it be "Front-End-Https" or "Front-End-HTTPS" - "WWW-Authenticate" or "Www-Authenticate" - specifying all lowercase removes ambiguity by standardising the field. This in turn simplifies handling the headers all round. – Leonorleonora

@Stadiometer It could be related to HPACK, the header compression algorithm used with HTTP2. It's certainly easier if it's all lowercase. Also it has a small static dictionnary : tools.ietf.org/html/rfc7541#appendix-A – Aestivation

Thanks @BorekBernard, I expanded the answer with your comment. – Adolphadolphe

Answer 4

header('Content-type: image/png') did not work with PHP 5.5 serving IE11, as in the image stream was shown as text

header('Content-Type: image/png') worked, as in the image appeared as an image

Only difference is the capital 'T'.

Hairpin

Then there is obviously a problem with the implementation because all header fields are supposed to read as case-insensitive. Apache Bench is also messed up. It doesn't like lowercase field names. – Article

Answer 5

They are not case sensitive. In fact NodeJS web server explicitly converts them to lower-case, before making them available in the request object.

It's important to note here that all headers are represented in lower-case only, regardless of how the client actually sent them. This simplifies the task of parsing headers for whatever purpose.

Alewife

That's because node/javascript is case-sensitive, so to simplify things they normalize everything to lower-case, meaning the HTTP headers in effect are case insensitive. – Boar

Which @Borek's comment on this answer indicates is the standard for HTTP/2: https://mcmap.net/q/53215/-are-http-headers-case-sensitive – Erotomania

Answer 6

officially, headers are case insensitive, however, it is common practice to capitalize the first letter of every word.
but, because it is common practice, certain programs like IE assume the headers are capitalized.
so while the docs say the are case insensitive, bad programmers have basically changed the docs.

Quaint

@Borek's comment on this answer indicate RFCs that are trending towards MUST use lower case https://mcmap.net/q/53215/-are-http-headers-case-sensitive. – Erotomania

Well that rfc says one thing, but browser compatibility says another, and one of those is more important – Quaint

It's a war, @Quaint , between community and proprietary. If community is more important then the RFC is more important, if private profit and private control is more important, then clearly, let's ensure support for browsers that flaunt the RFCs. – Erotomania

I have IETester which runs IE 6 and case-insensitive headers work just fine. I tested location, last-modified and cache-control headers. They seem to work normally even when they are given fUnky-caSe. I even checked the raw HTTP output using telnet and confirmed that Apache had not changed the case to Title-Case. – Mushroom

Answer 7

The RFC for HTTP (as cited above) dictates that the headers are case-insensitive, however you will find that with certain browsers (I'm looking at you, IE) that capitalizing each of the words tends to be best:

Location: http://stackoverflow.com

Content-Type: text/plain

vs

location: http://stackoverflow.com

content-type: text/plain

This isn't "HTTP" standard, but just another one of the browser quirks, we as developers, have to think about.

Allomorph

Could you provide any evidence on that? – Artair

I meant a concrete test case; I do have an IE to test with. – Artair

Why exactly does it tend to be best? – Boar

I will make a browser that sends headers with random capitalization just to screw with devs – Quaint

Except when using HTTP/2 which now invalidates upper case in header names according to @Borek's comment on this answer: https://mcmap.net/q/53215/-are-http-headers-case-sensitive – Erotomania