JSON Date format (without time) returning from an API

Question

Wondering if I should remove the time data normally stored. We're using postgres and node.js where a DateTime would get returned from our API as:

2013-07-01T00:00:00.000Z

Yet since this field should only represent a date, I feel reformatting before return like this would make it more clear that time is not relevant:

2013-07-01

Thoughts?

Answer 1

If you are representing a calendar date, there is no time or timezone. The short representation makes more sense.

Unfortunately, new Date(string) in many javascript implementations can do bad things to you.

new Date('2015-09-23')
Tue Sep 22 2015 20:00:00 GMT-0400 (Eastern Daylight Time)

The simplest way out of the problem is not to use javascript's Date - this type matches up with DateTimeOffset in other languages. It is a bad way to represent calendar date values.

But, you're probably going to use javascript's Date anyway. The next simplest "fix" is to avoid standard representations (since standard representations get interpretted as DateTimeOffset with UTC). Here are two possibilities:

Use "/" instead of "-".

new Date('2015/09/23')
Wed Sep 23 2015 00:00:00 GMT-0400 (Eastern Daylight Time)

Use a 3 digit month - the leading zeroes will be discarded.

new Date('2015-009-23')
Wed Sep 23 2015 00:00:00 GMT-0400 (Eastern Daylight Time)

If you have javascript on the both the client and server side, you're done. If you have something else on the server side, you should consider what the server language will do if it sees non-standard date formats coming in.

Answer 2

As an API user, I would much rather receive the long form of a date.

For a few reasons:

1. Time Zone: the long format actually has a time-zone built in. That's important.
2. Parsing: most languages will be able to read that long format as a native "Date" object. In some languages like C# & Java, that short date will need to be coerced into using the correct time zone. You also avoid Month/Day confusion with the long format.
3. Comparisons: if a user passes in a short date, is your API going to handle that correctly? A good API needs to look the same going in and out.