

HTTP API Design - markthethomas
https://github.com/interagent/http-api-design

======
pan69
This seems to be interesting:

    
    
      Use UTC times formatted in ISO8601
    
      Accept and return times in UTC only. Render times in ISO8601 format, e.g.:
    
      "finished_at": "2012-01-01T12:00:00Z"
    

So what if the time zone is important? E.g. the time a user purchased a
product. The UTC time is obviously consistent throughout the system but
presented without a time zone might not make an awful lot of sense to a user,
especially if the time zone is something plus or minus 10 hours.

Wouldn't an RFC 2822 formatted date make not more sense; "Thu, 21 Dec 2000
16:01:07 +0200". You still have your UTC but you are now capable to represent
the time to a user within a context that makes sense.

~~~
quesera
"Render" here means "by the API" (emit), not "to the user" (display).

In your example, you'd just present the time in the user's timezone, via a
rendering transformation.

The API shouldn't concern itself with formatting details, but absolutely the
end user should never see an iso8601 timestamp!

~~~
pan69
I understand what the context of render means here. However, consider you're
building a mobile app that calls this API, then where does the correct time
zone from? It could come from the user profile or maybe somewhere else. In any
case, it's much easier on the client to include the time zone specific to the
client making the call in the time stamp it self otherwise all clients will
have to do time conversions.

~~~
quesera
The correct timezone comes from the user's device. Mobile or desktop. There's
almost never a good reason for the API service to know the user's timezone.

Besides the unnecessary code complication and extra compute cycles on the
server side, why destroy your opportunities for caching the data?

