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 ;-).
answered Mar 7 ’12 at 23:22
10.4k44 gold badges3131 silver badges4444 bronze badges
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.
answered May 5 ’16 at 12:52
8,76722 gold badges3434 silver badges4545 bronze badges
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.
- 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.
- Extra processing for converting to UTC for storing in UTC format in the database.
- Readability of input/output.
- Readability of GET URLs.
- 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.
answered Nov 5 ’18 at 8:19
Mithun SreedharanMithun Sreedharan
42.9k6666 gold badges169169 silver badges229229 bronze badges
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.
answered Sep 5 ’19 at 19:48