Consistent use of date- and time-related types in endpoint responses

[wilkinsona]

The endpoints are currently inconsistent in the types that they use for date and time-related types in their responses. For example, the sessions endpoint uses long for creationTime and lastAccessedTime whereas the info endpoint uses a Date for the git info's commit.time and build.time.

An advantage of using a Date is that the format can then be controlled by the user via Jackson's serialisation configuration. An advantage of using a long is that the format doesn't change making it easier to document. Whichever way we go, we should try to make all of the endpoints consistent.

It's worth noting that when consuming a date-like type, the endpoint infrastructure requires the use of ISO 8601 offset date times. Aligning with that (thereby making the formats used in requests and responses consistent) is another option to consider.

[vpavic]

I was just about to open a similar issue, to consider harmonizing the date/time related types between AuditEventEndpoint (which serializes AuditEvent instances) and SessionsEndpoint.

Perhaps it should also be considered to use java.time.Instant (rather than java.util.Date) which is then easily serialized to ISO 8601 UTC representation using SerializationFeature.WRITE_DATES_AS_TIMESTAMPS.

I generally find this set of recommendations useful as a guide for addressing date/time related concerns while building an API.

[philwebb]

We're thinking OffsetDateTime is probably the best option. That should give ISO 8601 output, allow you to always get back to the UTC time but also have the timezone offset should you need it.

[wilkinsona]

In the interests of being relaxed about what we accept and strict about what we produce, I think the endpoints should consume OffsetDateTime but produce Instant. An Instant would, as @vpavic describes above, be converted to an ISO 8601 representation in UTC. Using Instant would ensure a consistent offset (none) for all timestamps in the responses. If we use OffsetDateTime that consistency could be lost and timestamps may have a variety of offsets.

[wilkinsona]

As part of this, we should ensure that any @JsonFormat annotations are removed (as was proposed in #11588).

[joshiste]

@wilkinsona SessionsEndpoint.SessionDescriptor is still using longs for timestamps...

[wilkinsona]

Thanks for the catch, @joshiste.