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
91 lines
3.6 KiB
ReStructuredText
91 lines
3.6 KiB
ReStructuredText
..
|
|
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
|
License.
|
|
|
|
http://creativecommons.org/licenses/by/3.0/legalcode
|
|
.. _headers:
|
|
|
|
======================
|
|
HTTP Header Guidelines
|
|
======================
|
|
|
|
Deprecated X-Foo Naming Scheme
|
|
------------------------------
|
|
|
|
In :rfc:`6648` the recommendation to prefix application-specific headers with
|
|
``X-`` was retracted. It is mentioned in :rfc:`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 :rfc:`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.
|
|
|
|
:rfc:`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-Policy
|
|
|
|
In these cases, adding ``OpenStack-`` as a prefix resolves the ambiguity, as
|
|
in::
|
|
|
|
OpenStack-Identity-Account-ID
|
|
OpenStack-Networking-Host-Name
|
|
OpenStack-Object-Storage-Policy
|
|
|
|
Avoid 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.1
|
|
|
|
.. note:: 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 CORS [1]_ 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.
|
|
|
|
.. [1] https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS
|