履歴データなどを取得するAPIを設計するとき、必ずつきまとうのが期間指定です。
履歴データの件数は青天井ですから全件取得で処理がパンクしないよう、開始日/終了日もしくは開始日時/終了日時を指定させることが普通です。
API上で指定するのが「年月日」だったとしても最終的にDBに問い合わせる際にはdatetime型に落とし込まれるので大体同じ話になるのですが、よくやってしまいがちな失敗が
●終了日時を○月○日23:59:59.999と指定するように作ってしまう
●すなわち、終了日時が「以下」という条件で働くようになっている
ことです。
終了日時が「以下」という条件で働くようにAPIを設計したとして、日時の精度はAPIに明記されているでしょうか?
日時の精度も仕様の一部として明記するとして、採用しているDBのバージョンアップにともない日時型データの精度が上がってしまう事態も有り得ますがその際に仕様が変わってしまうおそれはないでしょうか?
これが確定していなければ、呼ぶ側が「23:59:59.999」と指定すればいいのかあるいは「23:59:59.999999」と指定すべきなのか決定できないのです(9の数が足りていなければデータの取りこぼしが発生しますし、9が過剰なら四捨五入でデータの取り過ぎが発生します)。
そしてもちろん、時刻に限らず連続値の精度は決め打ちせずにすむならしないでおく方が当然APIとしての拡張性は高まります。
●時刻値の精度は非明示(もしくは最低保障精度だけ明示)に
●期間は「以上・未満」で指定(すなわち2015年一年間なら「2015-01-01 00:00以上、 2016-01-01 00:00未満」と表現)
するという規約にすることで精度面で拡張に対して開いたAPIとなります。