f75a52f7b7
I had to read the original note four times before it made sense to me. The problem, I think, was that it talked about 'old' and 'new' - but I don't have enough context to immediately remember which is old and which is new. Also, the new thing was first, and my brain wanted to make them be listed in the opposite order. It was also unclear to me for a bit which was the one I was supposed to use. Address those concerns by rewording the note to be clear that the first option is the desired one, and to refer to each of them as first and second rather than old and new. Change-Id: I1d51572eb57278e6b21224ca60516c528de42ee1
3.6 KiB
HTTP Header Guidelines
Deprecated X-Foo Naming Scheme
In 6648 the
recommendation to prefix application-specific headers with
X- was retracted. It is mentioned in 2616 as a
permanently-reserved prefix for implementors, but is deprecated due to
the complexities of migrating prefixed headers to standardized ones.
This has resulted in some standards reserving X-prefixed names in
addition to their non-prefixed headers. (see X-Archived-At/Archived-At)
In the more recent 7231#section-8.3.1 designers of new protocols are
discouraged from using X-prefixed headers and to keep new headers short
where possible.
Guidance
This does not mean it is recommended to replace
existing uses of X-, or in using X- in
private/local/development contexts. New APIs (or new API features)
should make their best effort to not use header names that conflict with
other applications. To do this, use "OpenStack" and the service name in
the header. An example might be "OpenStack-Compute-FooBar", which is
unlikely to be standardized already or conflict with existing
headers.
6648 intentionally
does not disallow using X- as a prefix, but does remove the
experimental/unstandardized semantics from the prefix. For existing
projects, it is acceptable to create new headers prefixed with X since
it is likely that the rest of the headers already standardized in the
API begin with X-.
Examples
Some good header names that are clear, unlikely to conflict, and
could become standardized might be
OpenStack-Identity-Status Some headers that are at risk for
conflicts might look like:
Account-ID
Host-Name
Storage-PolicyIn these cases, adding OpenStack- as a prefix resolves
the ambiguity, as in:
OpenStack-Identity-Account-ID
OpenStack-Networking-Host-Name
OpenStack-Object-Storage-PolicyAvoid Proliferating Headers
It can be tempting to use the names of headers as a way of passing specific information between the client and the server. Where possible this should be avoided in favor of using a more generic header name and placing the specifics in the value. For example compare the following two headers:
OpenStack-API-Version: compute 2.1
OpenStack-Nova-API-Version: 2.1Note
The first header is the recommended form. The second header is in the form of a microversion header currently in use. It effectively demonstrates the problem. Also note that whereas the second header uses a service name, the first header uses the more correct service type.
At first glance these header name and value pairs convey the same information, with the second option being a bit easier to parse on the server side. However consider the following problems when using the second form:
- A new header is needed every time there is a new service.
- It violates the principle that in key-value based data structures the key should be an accessor only, that is: It should be opaque and generic.
- If CORS1 middleware is being used, it needs to be configured to allow a multitude of headers instead of a generic one.
- Generic library code (in either the client or the server) that is supposed to deal with this class of header has to construct or parse strings on both sides of the name-value pair.