
HTTP API Design Guide - lobo_tuerto
https://www.gitbook.com/book/geemus/http-api-design/details
======
azdle
While this is a nice small collection of things that could be helpful when
designing and API, it would be infinitely more helpful if it gave any info on
why it's suggesting what it's suggesting.

[https://geemus.gitbooks.io/http-api-
design/content/en/founda...](https://geemus.gitbooks.io/http-api-
design/content/en/foundations/require-versioning-in-the-accepts-header.html)

Okay versioning is important, sure, but why put it in an accept header?

[https://geemus.gitbooks.io/http-api-
design/content/en/respon...](https://geemus.gitbooks.io/http-api-
design/content/en/responses/use-utc-times-formatted-in-iso8601.html)

Yep, UTC is the best (well except maybe TAI, but that's a much harder battle),
but why ISO8601, is it better than the other options for some reason?

~~~
niftich
Some explanation of rationale would help the guide immensely, especially on
short stub pages.

 _> but why ISO8601_

The guide's recommendation should be tightened to RFC 3339 instead [1], to
exclude less common formats like week-day and day-of-year that are defined in
ISO 8601.

The two biggest advantages of the advocated format are:

\- no redundant information, like day-of-week, which may cause trouble if the
redundant fields are in conflict

\- big endian throughout, therefore ASCIIbetically sortable for chronologic
ordering

[1] [https://tools.ietf.org/html/rfc3339](https://tools.ietf.org/html/rfc3339)

