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

User · Answer

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

User · Answer

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

User · Answer

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

User · Answer

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

User · Answer

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  -

[http] Recommended date format for REST GET API

Examples related to http

Examples related to url

Examples related to rest

Examples related to date

Examples related to get