RESTful API design - best practices for passing dates

Question

What is the best practice for sharing dates in an API?

Is it best to share dates with an SQL-like datetime format - 'YYY-MM-DD HH:MM:SS' with an optional timezone embedded inside of it?

Or is it best to use milliseconds based on UTC?

score 24 · Accepted Answer · edited Mar 30 '14 at 15:03

24

I prefer to encode times as full ISO 8601 dates, but with the constraint that my code only ever generates them in the UTC timezone. If you've got a good date parsing library (e.g., Jodatime for Java) accepting full ISO 8601 is not particularly difficult and they're at least somewhat readable. (Offsets from some epochal instant are nothing like as easy for people to read.)

edited Mar 30 '14 at 15:03

Chris Betti

2,721
2
27
36

answered Nov 28 '11 at 20:45

Donal Fellows

133,037
18
149
215

2

I assume we all mean ISO 8601? – fumanchu Nov 28 '11 at 20:59
7

No, I was talking about ISO 5775 on bicycle tires, or perhaps ISO 3632 on saffron… ;-) – Donal Fellows Nov 29 '11 at 00:39
1

For people looking for an example using this ISO: 2013-10-23T05:02Z (including Date and Time) – Ivo Pereira Oct 24 '13 at 10:20

score -1 · Answer 2 · answered Nov 28 '11 at 17:32

-1

It's up to you but, unless you are doing some kind of calendar application, I wouldn't bother with supporting the full ISO format because parsing them while handling the timezone, daylight saving time, etc. can quickly become very complex. Passing them as UTC is almost always good enough, and it's easy for the programmers using your API to convert any date they have to this format.

answered Nov 28 '11 at 17:32

laurent

88,262
77
290
428

2

-1 for encouraging institutional knowledge. -1 for not explicitly stating timezone. – maletor Jan 26 '12 at 01:27
2

-1 It is easy to return UTC zoned datetimes in ISO 8601 format. You do not have to choose one or the other. – Chris Betti Mar 30 '14 at 14:55

RESTful API design - best practices for passing dates

2 Answers2