Recommended date format for REST GET API

Question

What's the recommended timestamp format for a REST GET API like this:

http://api.example.com/start_date/{timestamp}

I think the actual date format should be ISO 8601 format, such as YYYY-MM-DDThh:mm:ssZ for UTC time.

Should we use the ISO 8601 version without hyphens and colons, such as:

http://api.example.com/start_date/YYYYMMDDThhmmssZ

or should we encode the ISO 8601 format, using for example base64 encoding?

Solution 1

REST doesn't have a recommended date format. Really it boils down to what works best for your end user and your system. Personally, I would want to stick to a standard like you have for ISO 8601 (url encoded).

If not having ugly URI is a concern (e.g. not including the url encoded version of :, -, in you URI) and (human) addressability is not as important, you could also consider epoch time (e.g. http://example.com/start/1331162374). The URL looks a little cleaner, but you certainly lose readability.

The /2012/03/07 is another format you see a lot. You could expand upon that I suppose. If you go this route, just make sure you're either always in GMT time (and make that clear in your documentation) or you might also want to include some sort of timezone indicator.

Ultimately it boils down to what works for your API and your end user. Your API should work for you, not you for it ;-).

Solution 2

Check this article for the 5 laws of API dates and times HERE:

• Law #1: Use ISO-8601 for your dates
• Law #2: Accept any timezone
• Law #3: Store it in UTC
• Law #4: Return it in UTC
• Law #5: Don’t use time if you don’t need it

More info in the docs.

Solution 3

Every datetime field in input/output needs to be in UNIX/epoch format. This avoids the confusion between developers across different sides of the API.

Pros:

• Epoch format does not have a timezone.
• Epoch has a single format (Unix time is a single signed number).
• Epoch time is not effected by daylight saving.
• Most of the Backend frameworks and all native ios/android APIs support epoch conversion.
• Local time conversion part can be done entirely in application side depends on the timezone setting of user's device/browser.

Cons:

• Extra processing for converting to UTC for storing in UTC format in the database.
• Readability of input/output.
• Readability of GET URLs.

Notes:

• Timezones are a presentation-layer problem! Most of your code shouldn't be dealing with timezones or local time, it should be passing Unix time around.
• If you want to store a humanly-readable time (e.g. logs), consider storing it along with Unix time, not instead of Unix time.

Solution 4

RFC6690 - Constrained RESTful Environments (CoRE) Link Format Does not explicitly state what Date format should be however in section 2. Link Format it points to RFC 3986. This implies that recommendation for date type in RFC 3986 should be used.

Basically RFC 3339 Date and Time on the Internet is the document to look at that says:

date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.

what this boils down to : YYYY-MM-ddTHH:mm:ss.ss±hh:mm

(e.g 1937-01-01T12:00:27.87+00:20)

Is the safest bet.

Solution 5

Always use UTC:

For example I have a schedule component that takes in one parameter DATETIME. When I call this using a GET verb I use the following format where my incoming parameter name is scheduleDate.

Example:
https://localhost/api/getScheduleForDate?scheduleDate=2003-11-21T01:11:11Z

View more solutions

Comments

[Lorenzo Polidori]

Thanks, very useful answer. I think I will go for the compressed version of ISO 8601 (i.e. http://api.example.com/start_date/YYYYMMDDThhmmssZ) which is good for readability and clean URLs.

[Radu Potop]

But JSON does have a recommended date format and it's ISO 8601 :)

[Radu Potop]

@stalemate Date objects by default serialize as a string containing the date in ISO format. developer.mozilla.org/en-US/docs/JSON

[nategood]

@RaduPotop Yes, but this is HTTP and URI standards we're talking about. I'm not sure what JSON has to do with it.

[user5670895]

I just want to note that hyphens do not need to be URL-encoded.

[Iain]

-1, as 2017-11-20T11%3A00%3A00Z is just not very readable. Also (IIS-specific) it seems to be very paranoid about colons in URLs even if they are encoded.

[Andy Dufresne]

This link - agiletribe.wordpress.com/2015/06/10/jsonrest-api-handling-da‌​tes recommends integer epoch to avoid human readability problems that could be experienced with iso-8601 format. Let me know if you have different views.

[Andy Dufresne]

This link - agiletribe.wordpress.com/2015/06/10/jsonrest-api-handling-da‌​tes recommends integer epoch to avoid human readability problems that could be experienced with iso-8601 format. Let me know if you have different views

[Bruce Adams]

Note that hyphens and dots are not reserved characters in URLs. Only the colons require URL encoding (en.wikipedia.org/wiki/Percent-encoding). In ISO-8601 (en.wikipedia.org/wiki/ISO_8601) the hyphens are required but the colons are optional. So correct ISO-8601 variants to use in URLs are YYYY-MM-DDThhmmssZ and YYYY-MM-DDThhmmss.mmmZ if you need greater precision.

[kaay]

A frequently linked and heavily debated article. While I agree with the choice of a sortable format if it must be a string at all, a unix timestamp (which the article does not even acknowledge) has every one of the stated benefits and more. Until presentation, the issues of timezones and daylight savings (and political decisions) don't even exist.

[Jorge.V]

Couldn't agree more.

[jamesjansson]

The only thing that I would add to this is consider from the outset whether you will need to consider milliseconds anywhere in your system. If so, use the millisecond version of the Unix timestamp.