Recommended date format for REST GET API

http url rest date get
Lorenzo Polidori picture Lorenzo Polidori · Mar 6, 2012 · Viewed 141k times · Source

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?

Answer

mohamed-ibrahim picture mohamed-ibrahim · May 5, 2016

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.

Related questions

Place API key in Headers or URL

I'm designing a public API to my company's data. We want application developers to sign up for an API key so that we can monitor use and overuse. Since the API is REST, my initial thought is to put this …

Read More
URL matrix parameters vs. query parameters

I'm wondering whether to use matrix or query parameters in my URLs. I found an older discussion to that topic not satisfying. Examples URL with query params: http://some.where/thing?paramA=1&paramB=6542 URL with matrix params: http://some.…

Read More
Different RESTful representations of the same resource

My application has a resource at /foo. Normally, it is represented by an HTTP response payload like this: {"a": "some text", "b": "some text", "c": "some text", "d": "some text"} The client doesn't always need all four members of this …

Read More