How to Handle Dates and Time Zones in Spring REST APIs
Handle dates and time zones in Spring REST APIs: use Instant and ISO 8601, set Jackson and database zones, bind query dates and test across time zones.

Dates in an API go wrong in the same few ways. A client in Sydney sends midnight and the server stores the previous day. A timestamp serialised as a number loses its meaning when another service reads it. A test passes on the developer's laptop in London and fails on CI in UTC. The fix is not a library but a policy: decide what each date field means, pick the Java type that carries exactly that meaning, serialise it in one unambiguous format and convert to a local time only at the edge. This post applies that policy to a Spring REST API on Spring Boot 4, Jackson 3 and JDK 25.
Choose the type by meaning
Java's java.time package has a type for each meaning. Use the one that matches, not the one that is closest.
| Meaning | Example | Type | JSON |
|---|---|---|---|
| A moment on the timeline | When an order was placed | Instant | "2026-03-01T14:30:00Z" |
| A calendar day | A birthday, an invoice due date | LocalDate | "2026-03-01" |
| A wall-clock time without a day | Shop opens at 09:00 | LocalTime | "09:00:00" |
| A moment plus the zone it happened in | A flight departure in local time | ZonedDateTime or OffsetDateTime | "2026-03-01T09:30:00+01:00" |
| A day and time with no zone | A recurring local appointment | LocalDateTime | "2026-03-01T09:30:00" |
Instant is the right type for almost every audit and event timestamp, since it is unambiguous: it is a point in time, with no zone to misinterpret. LocalDate is for things that are dates in the calendar sense, and it must never be an Instant at midnight: a birthday of 1 March stored as 2026-03-01T00:00:00Z becomes 28 February in New York. LocalDateTime is the dangerous one, because it looks like a timestamp and has no zone, so two systems can read it as two different moments. Use it only for values that really are local, such as "the meeting is at 9:30 wherever you are", and document the meaning. Where the user's zone matters, such as scheduling an event for them, store the Instant or the local time together with a separate zone id (Europe/Berlin), not an offset, since offsets change with daylight saving time.
The java.util.Date, Calendar and SimpleDateFormat classes are legacy; the type overview is in the Java Date and Time tutorial, and the basic types are in data types.
Configure Jackson
Spring Boot registers the java.time support in Jackson automatically. Without it you get the error in LocalDate serialization. What you must set is the output format:
spring.jackson.serialization.write-dates-as-timestamps=false
spring.jackson.deserialization.adjust-dates-to-context-time-zone=falseWith the first, Instant is written as an ISO 8601 string, like 2026-03-01T14:30:00Z, which matches RFC 3339 and is readable in a log, instead of a number such as 1772375400.000000000. The second stops Jackson from shifting a parsed offset into the server's zone, which would hide what the client sent. Jackson 3, which Boot 4 uses, changed some defaults and package names; the property names above are the ones documented in the Boot reference for the release you use, so verify them against it after the upgrade. Keep the format fixed on both sides: clients send and expect ISO 8601 with a Z or an offset, never a locale format like 01/03/2026, which means different days in different countries.
Query and path parameters
Dates in URLs are strings, and you tell Spring how to read them:
@GetMapping("/reports")
List<Report> list(
@RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate from,
@RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate to) {
return reports.between(from, to);
}
@GetMapping("/events")
List<Event> since(@RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME) Instant since) {
return events.after(since);
}ISO.DATE accepts 2026-03-01, and ISO.DATE_TIME accepts a full timestamp with an offset. A value in the wrong format gives a 400 with a conversion message. Decide the semantics of a date range and write it down: is to inclusive? A report from 2026-03-01 to 2026-03-31 that excludes the last day is a common bug. Half-open ranges (from inclusive, to exclusive) compose cleanly. The converters are described in Spring's formatting reference.
Run everything in UTC
Set the JVM and the database to UTC, so there is no ambient zone to depend on:
java -Duser.timezone=UTC -jar shop.jarand in Hibernate, spring.jpa.properties.hibernate.jdbc.time_zone=UTC. Column types matter: PostgreSQL's timestamptz stores an instant, while timestamp stores a local value with no zone, and mapping an Instant to the latter makes the stored value depend on the connection zone. Use timestamptz for Instant, date for LocalDate. The mapping options are listed in mapping java.time types. A container's default zone is usually UTC already; a developer laptop is not, which is why the next two sections exist.
Inject a Clock
Code that calls Instant.now() is untestable: you cannot assert on it, and a test that crosses midnight fails once a day. Inject a Clock and ask it:
@Configuration
class TimeConfig {
@Bean Clock clock() { return Clock.systemUTC(); }
}
@Service
class OrderService {
private final Clock clock;
OrderService(Clock clock) { this.clock = clock; }
Order place(Cart cart) { return new Order(cart, Instant.now(clock)); }
}In a test, use Clock.fixed(Instant.parse("2026-03-01T10:00:00Z"), ZoneOffset.UTC). Time-dependent tests then give the same answer on every machine. Timeouts in tests are a separate matter, covered in JUnit timeouts.
Test it
Run the suite with a non-UTC default zone to flush out accidental dependence: -Duser.timezone=Pacific/Auckland is a good choice since it is far from UTC and uses daylight saving. A test that fails there has a hidden assumption.
@Test
void a_birthday_stays_the_same_day_in_any_zone() {
var previous = TimeZone.getDefault();
TimeZone.setDefault(TimeZone.getTimeZone("America/Los_Angeles"));
try {
var person = json.readValue("{\"birthday\":\"2026-03-01\"}", Person.class);
assertEquals(LocalDate.of(2026, 3, 1), person.birthday());
} finally {
TimeZone.setDefault(previous);
}
}Add tests around daylight saving boundaries for anything that adds durations or schedules recurring events; "one day later" and "24 hours later" differ twice a year.
What to tell API clients
Put the rules in the API description, in one paragraph clients cannot miss: instants are ISO 8601 with a Z, calendar dates are YYYY-MM-DD, ranges are half-open, and the server never interprets a date in a zone of its own. In OpenAPI, declare the format as date-time or date on each field, so generated clients use the right types. A client library that turns a date string into a midnight timestamp in the browser's zone reintroduces the original bug on the other side of the wire, so test one generated client against a non-UTC machine before you publish the spec.
Where this stops
This covers moments and dates that your API exchanges. Recurring schedules, business calendars, public holidays and leap seconds need their own models, and the zone database itself changes: governments change rules, and the JDK ships the tzdata that your servers have. Keep the JDK updated, or update the zone data on its own. RFC 3339, the profile of ISO 8601 used here, is at rfc-editor.org.


