Topic: "X-" or "X-COMPANY-" prefix for custom headers

[msmoljan]

Based on this SO answer I think it might be a good idea to recommend (but not enforce) using the X- or X-COMPANY- prefix in custom header names.

This would help distinguish them from standard headers.

[siemensikkema]

@msmoljan good suggestion 👍 This affect both request and response headers, right? That kind of breaks the structure we have. Unless we duplicate it under both the Request and Response section, or create a common section. Thoughts?

[msmoljan]

It could probably be used for response headers too, but I can't imagine any special use cases at the moment.

My initial idea was more focused on request headers. I actually got it from a project where they could be really useful in the future.

But I also haven't put any deeper thought into it, so I'm looking forward to your input!

What does it break in the current structure?

[siemensikkema]

@msmoljan usage in response headers is a thing, eg: https://www.keycdn.com/support/custom-http-headers

The thing with the structure I'm talking about is that we currently have this:

Requests
- URLs
- Request Headers
Responses
- Response Body
- Use null or unset keys that are not set
- Status Codes

This already contains a Request headers subsection and it would make sense to add a Response headers section but then where do we put this custom headers stuff? We could put it under requests and link to it from an otherwise empty subsection under Responses.

[Casperhr]

What is the point in passing this header around?

[msmoljan]

@siemensikkema sure, I'm fully okay with using the X- prefix in response headers.

I'll look into the sections when I have some time and see if I can find some fit.

@Casperhr it's about differentiating custom headers and standard headers, and from preventing them from colliding.

For example, there's a languageCode path item in one of our projects that we might want to move to a header at some point. Language-Code as a header name sounds fairly general. People might not know if it's a standard HTTP header or a custom one without checking the documentation. With X-Language-Code it's immediately obvious that it's a custom header.

Using X- also prevents us from unintentionally overriding an existing standard header.

[Casperhr]

Oki got it, Yes X-Insert-Stuff-Here used to be the standard for custom headers

I see more today that people use

Insert-Stuff if the header is not conflicting with standard names

[msmoljan]

Yeah, so the point is to introduce the X- prefix to make the separation between custom and standard clear without needing to think about conflicts and which is which.

[Casperhr]

Yes this is old shool. Was common 10years back

[msmoljan]

Personally, regardless of it being old-school, I see it as a good convention. The "new" way is basically not to differentiate, so it forces you to keep track of standard headers either in your mind or to make sure you keep looking them up.

The convention would also keep us future-proof in case new standard headers get introduced. Sure that's a bit of a stretch, but it's still one less thing to think about :)

So in the end we just need to decide if we want to give this one a 👍 or a 👎.

[Casperhr]

If the group wants to go for this I'm fine. It was the standard way when I started backend. So have no issue with it