Skip to content
javahacks.dev
Spring MVC

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.

6 min read
Summarize in AI
Flat illustration of a browser and a server trading a request and a response, with the Spring, OpenJDK, NGINX and Postman logos.

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.

MeaningExampleTypeJSON
A moment on the timelineWhen an order was placedInstant"2026-03-01T14:30:00Z"
A calendar dayA birthday, an invoice due dateLocalDate"2026-03-01"
A wall-clock time without a dayShop opens at 09:00LocalTime"09:00:00"
A moment plus the zone it happened inA flight departure in local timeZonedDateTime or OffsetDateTime"2026-03-01T09:30:00+01:00"
A day and time with no zoneA recurring local appointmentLocalDateTime"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:

src/main/resources/application.propertiesproperties
spring.jackson.serialization.write-dates-as-timestamps=false
spring.jackson.deserialization.adjust-dates-to-context-time-zone=false

With 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:

src/main/java/com/example/web/ReportController.javajava
@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:

Shell
java -Duser.timezone=UTC -jar shop.jar

and 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:

java
@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.

java
@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.

Also inJava Core
Taggedhow to
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.