REST接口JSON请求体中日期参数传输规范：Long类型是否最优？

Great question—this is such a common headache when building and consuming REST APIs, especially when you control both client and server. Let’s break down your options, including the Long timestamp approach you prefer, and talk about standards vs. team conventions.

1. 你提到的Long时间戳方案：便捷但需明确约定 #

Using a Long (timestamp) to transmit dates is absolutely a valid approach, and it’s easy to see why you like it—no messing with date formats, parsing errors, or timezone confusion (as long as you agree on the basics).

• Pros:
  • Super lightweight and fast to serialize/deserialize—most languages have built-in methods to convert timestamps to date objects (e.g., Java’s new Date(timestamp), JavaScript’s new Date(timestamp)).
  • Eliminates format mismatches (no arguing over MM/DD/YYYY vs DD/MM/YYYY or missing timezone info).
• Critical Caveat: You must explicitly agree on two things with your team:
  • Is the timestamp millisecond-precision (most common in Java/JS) or second-precision (Unix timestamp standard)? Mixing these up will cause off-by-thousands-of-seconds bugs that are a nightmare to debug.
  • Is the timestamp based on UTC? Always use UTC as the baseline to avoid timezone drift between client and server.

This works perfectly for internal APIs where you control both ends—no need for external standards, just clear team documentation.

2. ISO 8601：行业标准的最优方案 #

If you’re looking for a more standardized approach (especially for public APIs or when working with external teams), ISO 8601 formatted strings are the de facto standard for REST APIs. Examples include:

• UTC time: "2024-05-20T14:30:00Z" (the Z denotes UTC)

• Timezone-aware: "2024-05-20T10:30:00-04:00" (Eastern Daylight Time)

• Pros:

  • Human-readable—you can look at the string and immediately know the date/time without converting a timestamp.
  • Built-in timezone information—no guessing if the date is in local time or UTC.
  • Widely supported by frameworks: Most modern tools (Spring Boot’s Jackson, Node.js’s date-fns, Python’s datetime) automatically handle ISO 8601 parsing/serialization out of the box.
  • Aligns with REST best practices and specs like OpenAPI, which explicitly recommend ISO 8601 for date/time fields.

3. Which should you choose? #

There’s no one-size-fits-all answer, but here’s a quick guide:

• Go with Long timestamps if:
  • You own both client and server, and your team values simplicity/performance over readability.
  • You’re dealing with high-volume data where every byte counts (though the difference between a timestamp and ISO string is minimal for most cases).
• Go with ISO 8601 if:
  • You’re building a public API or working with external teams—standardization reduces friction.
  • Debuggability is important (being able to read dates in logs/API responses saves time).
  • You want to align with industry best practices and avoid future tech debt if your API needs to scale to external users.

Final Tips #

Whichever approach you pick:

• Document it clearly in your API docs (e.g., "Timestamp: milliseconds since 1970-01-01 UTC" or "Date format: ISO 8601 UTC string").
• Avoid custom date formats (like "2024/05/20" or "May 20, 2024")—these are prone to parsing errors across different locales and frameworks.

内容的提问来源于stack exchange，提问作者Miki