title: REST API semantics for querying dates/times?
body: <p>I have a node.js application that stores many dates in a database.  They are stored in the ISO format, such as <code>'2016-11-02T16:30:12-04:00'</code>.</p>
  
  <p>Some fields which are dates are just dates, other are date/times.  An example of a date/time would be "last modified" for a record, where a person's birthday is just a date.</p>
  
  <p>The question is about best practices for storage and query patterns on these things.  Because a date always has a time, you must choose how to store for example a birthday.   <a href="http://apiux.com/2013/03/20/5-laws-api-dates-and-times/" rel="nofollow noreferrer">Following the 5 laws of API dates and times</a> this is of course done in UTC.</p>
  
  <p>There are edge cases though where proper API behavior seems unclear.  Suppose someone submits a birthdate to the API of <code>'2016-11-02T16:30:12-04:00'</code>.   This is bad news, because a search like <code>/users?birthdate=2016-11-02</code> will fail, as that date will get converted to <code>'2016-11-02T00:00:00Z'</code> and fail to match in the DB.  What then should correct behavior be?</p>
  
  <ol>
  <li>When someone <code>POST</code>s a user, convert date fields into dates at midnight UTC, and then have the convention that querying birthdates should assume the same?</li>
  <li>Convert date queries for certain fields into implicit ranges, i.e. searching for <code>2016-11-02</code> is really looking for <code>2016-11-02T00:00:00Z &lt;= x &lt;= 2016-11-02:23:59:59Z</code>?</li>
  <li>Match only on the exact moment, and rely on the client to know that a birthday of <code>'2016-11-02T16:30:12-04:00'</code> really means 4:30PM EST, and does not mean just on November 2nd?</li>
  </ol>
  
  <p>What's the established pattern / best practice here for distinguishing between dates and datetimes?</p>