I am working on a service in a sprint boot microservice application. The consumer for my service can be another service, as well as a UI component.

The are 5 entities in my service, each entity having it's own set of CRUD APIs. Four of these entities have two datetime fields - event_start_date_time and event_end_date_time, where I store date and time without timezone (as it is assumed that the consumer will send datetime in UTC). For ex:


In one of the entities though, only date is needed - start_date and end_date. However, for the sake of consistency, like in other entities, I have been instructed to use datetime here as well. So if the user wants to book something from 2020-01-01 to 2020-01-05, it should be represented like this -


Now my question is, should I expect from the consumer to send the data in above format (appending 00:00:00 and 23:59:59 to the dates)? Or should my service handle this?

If the consumer does this, then he can add some other time as well, like instead of 00:00:00 and 23:59:59, might put 00:00:05 and 14:00:00. My service can ignore consumer's time input and add correct one itself, but then it would be like discrediting the actual data that consumer has sent.

If my service is to handle it, then the API will only have date and I will be appending time part to it. But this way, it will not be consistent with the other 4 entities.

What can be the best way to do it?

Any other way to do is appreciated as well, just remember that it has to be date and time both.


  • 3
    If the requester is in one time zone and the data source is in a different time zone, for the sake of correctness of operations (Principle of Least Astonishment, POLA), the middle software have to widen the date range by one day where necessary. Then, the middle software may have to perform additional filtering to remove unneeded entries after the time zone differences have been applied. (Posted as comment since this is a short one.) It is a POLA violation if an API doesn't behave like what any programmer would expect it to do.
    – rwong
    Sep 19, 2020 at 20:12
  • @rwong How does it matter if the data source is in any time zone? If we plan to store date and time without timezone, then all data source has to do is store or return based on query params (from and to datetime).
    – rsp
    Sep 19, 2020 at 20:26
  • 3
    Any API should come with a description/documentation of it's semantics. If you are the one who writes the description, then define it the way you think it should work. If someone else writes the description, ask them. If there is currently no such description, then offer your superiors to create one.
    – Doc Brown
    Sep 19, 2020 at 22:55
  • 1
    @RajyawardhanSinghPanwar If both sides agree that datetime are always in the same time zone (i.e. the entire software system simply doesn't need to be concerned with time zone at all), it can be represented as having an "unspecified time zone" (that's what it's designed for), and do not perform any conversion whatsoever. For example, subtracting 12:00pm on the day before daylight saving time from 12:00pm on the day after daylight saving time should still yield 24 hours, even if the correct answer should have been 23 or 25 hours when calculated in UTC.
    – rwong
    Sep 20, 2020 at 0:41
  • 1
    As for parsing (i.e. converting datetime to just date), all of the options are available: rounding down (converting the start datetime to just the date), rounding up (converting the end datetime to the end of that date, or the beginning of the following day), or rounding to the nearest date (beginning of the day if before 12:00pm, end of the day if on or after 12:00pm) etc. It's best to ask first, and then to document the decision.
    – rwong
    Sep 20, 2020 at 0:44

1 Answer 1


If you have been instructed to use datetime in the API although the service deals in dates only, you should request clear guidance from the authors of your requirements about how to handle non-canonical inputs such as timestamps which are not at start/end of the day or just date values which you might receive from clients who assume that since only dates are required the API spec may be wrong (yes that happens.)

You may guess how to best do it, we also may guess but may be more likely to be wrong since we know less about the project. If specifications are open to guessing, it's possible that your interpretation differs from that of other readers of the specification, resulting in incompatible implementations and perceived bugs.

Getting unambiguous specs early is the best way to prevent this kind of problems.

  • I have thought over it for some time and couldn't come to a rational conclusion as to which approach to follow. Anyone can be implemented, but none seem correct. I agree it's better to clear with my instructors.
    – rsp
    Sep 19, 2020 at 18:38

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.