api-guidelines
api-guidelines copied to clipboard
microsoft
Improve guidance on date-time values passed in headers
The current Azure API Guidelines state (though maybe not clearly) that date-time values passed in headers should be formatted as RFC 1123 date-time strings. And certain headers. such as "Date" and the OASIS "Repeatability-First-Sent" explicitly require this format.
But OpenAPI (both v2 and v3) say that "date-time" values should be sent in RFC 3339 format. And Azure APIM enforces this format for services hosted through APIM.
This raises a few questions:
- How should headers that require RFC 1123 format be described in the API definition? With "format: date-time"? Without "format" at all? With some custom "format" (autorest reported uses "date-time-rfc1123")?
- What about other headers that contain date-time, like "if-modified-since"? Which format should we recommend be used there?
@johanste said:
Regarding date formats in headers, the way I read https://www.rfc-editor.org/rfc/rfc7231 - section-7.1.1, it encourages the use of HTTP-date for timestamps in headers. (One could make an argument that since the next and only subsection deals specifically with the Date header that it only applies to this specific header, but I don’t believe that to be the intent)
We should decide and then ensure that the Azure API Guidelines / API Style Guide are clear on these points.
Actually, "if-modified-since"/ "if-unmodified-since" are also clearly defined in RFC 7232 as an "HTTP date" -- RCF 1123.
https://datatracker.ietf.org/doc/html/rfc7232#section-3.3
Capturing a comment from a side discussion on this topic:
as an example of RFC 822's [the basis of RFC 1123] horribleness to work with, it allows timezones like "CDT" which require a regularly updated database of decisions made by politicians to calculate a true date-time value
It is perfectly fine for us to provide guidance that disallows such use in Azure services. Which would make it more of a theoretical problem than a real one.
A closer reading of RFC 7231 shows that it recommends (but does not mandate) that date-times always be expressed in GMT:
The preferred format is a fixed-length and single-zone subset of the date and time specification used by the Internet Message Format
So we should maybe make this a requirement in the Azure API Guidelines.