HTTP API Design | Hacker News Reader

HTTP API Design

github.com

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.

You can also use timezone offsets with 8601 in a similar way: 2000-12-21T16:01:07+0200.

"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!

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.

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?

Reply on news.ycombinator.com