How to implement intervals?

[ePaul]

Rule 127 describes intervals (i.e. a range of date-times, with some special open-ended ones), and suggests to use these with ..._between query parameters instead of a pair of ..._before and ..._after query parameters.

In the API guild meeting of 2024-04-16, we found that this is not quite easy to implement, e.g. the standard java.time API doesn't even has a type representing it and Joda time's Interval doesn't support open-ended intervals. Guava's Range\<Instant> could work, but needs a manual parser. (Same issue likely exists for other languages.)

We should get a section in the best practices chapter giving some ideas of how to implement this (@tkrop mentioned an example (internal link)), or alternatively rethink this recommendation.

[tkrop]

Intervals or periods following the ISO-8601 standard restricted by RFC-3339 are actually quite simple to implement using date-time and duration implementations: The delimiter / is required and unique for the interval context. It can be used to split the first and the second part of the interval expression and use standard time parsers. In worst case start- and end-value need to consider 3 cases:

1. The open ended marker ..,
2. The period starting with a uniq P at the begin (that can be simply transformed with help of the anchor value into a date-time-(offset) value, and
3. The standard date-time-(offset) provided as an anchor of the interval.

In most cases it will never be necessary too define operations on the date-time-(offset) pair defined by the interval. The start and end-values can just be forwarded to the ORM wrapper and translated into the query condition.