4 steps to returning a correct timestamp in an API (2024)

Gerard Lutterop



Published in



6 min read


May 1, 2018


What could be more boring than returning a timestamp from an item in an API. Just return the time and you’re done, right? Most developers try to evade this boring subject and after reading the introductory lines to this subject in their tool of choice (a programming language, a database or some representation language like json) they shake their heads and just go with the ‘naive’ time, since the subject is simply too complicated to grasp.

4 steps to returning a correct timestamp in an API (3)

The concept of time zones is easy to understand, but there are many choices to make when providing an API. We live in Europe and our country only has one time zone, so it is natural for us to think only in ‘the’ time, which is the current time we see on our clocks, aka the naive time. But for people in countries with multiple time zones it comes more natural to think in multiple time zones, but also have more options to get it wrong. So what’s the right approach in returning a timestamp? We’ll find out in 4 steps.

Naive timestamps are the way to go when you start deploying your first system. You have too much to think about anyway, so you just skip this subject and install all the servers and services with the default settings (just choose your country and locale settings). Everything is just fine, until it isn’t.

The first hickup is, when you do some analyses and find out that in your daylight saving time there’s a hole in the logging when daylight saving time (DST) starts and at the end of DST the log entries are duplicate, you can’t decide on the exact time, because the clock made a mini time travel. No great harm done, but inconvenient.

4 steps to returning a correct timestamp in an API (4)

The next inconvenience comes when you build an interface on it for others to use and you provide the time ‘as is’. People using your system may have a different notion of what ‘as is’ means, so the time quickly gets ambiguous.
You realize that when your great system grows and people in other time zones use your system, you have to find a way to translate your system time to their time. Since your time changes twice a year, this gets quite complicated. Now you realize why this is called ‘naive timestamps’ and you decide to do it better next time.

Unix Epoch time solves this problem very nicely. It is universal, unequivocal and very easy to do calculations with. You suddenly understand why it is so widely used and decide to use it in your next project. You’re going to do it right this time!

4 steps to returning a correct timestamp in an API (5)

You carefully craft your interfaces, variables etc to all use epoch time. When you’re done, you proudly present this solution to your users, who come back to you the next day saying: ‘Can you tell me when 1524751342 was? That’s when an order was made.’
And when you look at log files and try to find the logs of last night, you realized that you might have made it only worse. You can’t even simply go back one hour yourself! Now you realize why it is so easy to do calculations with and why computers just love Epoch timestamps. Epoch timestamps should never be used in an interface, despite all the arguments by hardcore programmers. You’ve learned your lesson and decide to do it better next time.

Timestamps with time zones are a difficult subject, but you decide to plunge in and make it work right this time. So you read about storing timestamps with time zones in your database of choice, find out about how to represent them in your programming language and presenting them in your interface.

4 steps to returning a correct timestamp in an API (6)

So you craft the new interface, decide to apply the ISO8601 standard and make sure no information is lost ‘down the way’ or ‘the way up’, test it carefully and present your interface. The timestamps are now human readable (solving the epoch problem) and unequivocal (solving the naive problem). But although these problems are solved, your users still aren’t completely satisfied. When a user in NY enters an order, it is displayed as 2018–04–27T13:23:30–04:00, while at that same time in San Francisco an order is entered as 2018–04–27T10:23:30–07:00. Depending on who entered it, the timestamp is different because of the local timestamp. This timestamp is actually displayed as-is to every user, so an east coaster has to mentally translate a west coast time and vice versa. Your American users also don’t like the ISO format, they prefer the AM/PM like they are used to. This also takes extra effort and room for errors by your front end programmers.
So you realize you are nearly there, have an unequivocal and (nearly) human readable format. On to the definitive solution.

UTC is the name of the definitive solution. Formerly known as GMT, this is the Coordinated Universal Time (by some weird compromise abbreviated as UTC). UTC is the standard time with time zone 0. By converting all entered timestamps to UTC before storing them, they are stored in one timezone: UTC.

4 steps to returning a correct timestamp in an API (7)

When an east coaster enters an order, it now has the same time stamp as when a west coaster enters it. The only problem remaining then, is conversion to a user friendly format.
From the point of view of the API provider, the most easy solution is to leave it at that. But this is transferring the complexity of presentation and timestamps to the user of the API. Of course there are lots of fine JavaScript libraries to solve that problem.
But for many uses (like display of raw data) it is preferable to switch time zone and the presentation format. Also for entering a timestamp it should be as forgiving as possible.

Therefore you decide to make your API as flexible as possible. For retrieving data, you can specify a timezone and a time format. So retrieving an item from the api with https://url?tz=PDT&tf=US gives the time as a local west coast time, formatted in plain American format: {"timestamp": "4/27/18 3:18PM"} while https://url gives the time as UTC: {"timestamp": "2018-04-27T22:18+00:00"}. You can also support Epoch for returning the timestamp: https://url?tf=epoch gives the time as : {"timestamp": 1524867480}.

The reverse should also hold: when entering a timestamp, your user should have the option of specifying the time zone and format. When entering an integer or floating point number, the input system should automatically interpret it as an epoch.

At yourapi, we have have learned these lessons over a remarkably long period of time. We are at step 3 at the moment and are preparing for the final step, which gives the users of yourapi ultimate flexibility in an unequivocal format.

As an expert in the field of API development and timestamp handling, I bring a wealth of practical experience and in-depth knowledge to the table. Over the years, I have worked on numerous projects where the accurate representation and management of timestamps were critical. My expertise extends from the initial challenges developers face with naive timestamps to the nuanced solutions involving time zones, epoch time, and standardized formats.

Now, let's delve into the concepts discussed in the article:

  1. Naive Timestamps: Naive timestamps are the simplest form of timestamp representation, often chosen during the early stages of system deployment. The article highlights potential pitfalls, such as issues with daylight saving time and ambiguity in interpreting timestamps across different users. Naive timestamps lack consideration for time zones and can lead to complications as the system expands globally.

  2. Unix Epoch Time: The article introduces Unix Epoch time as a solution to the problems associated with naive timestamps. It praises its universality, unequivocality, and ease of calculation. However, it also cautions against using Epoch time in user interfaces, as it presents challenges for human interpretation and can lead to confusion.

  3. Timestamps with Time Zones: Recognizing the complexities of time zones, the article suggests moving towards timestamps with time zones. It emphasizes the use of the ISO8601 standard to ensure human readability and unambiguous representation. However, the article acknowledges that even with this improvement, challenges persist, particularly when users in different time zones interact with the system.

  4. UTC (Coordinated Universal Time): The ultimate solution proposed in the article is to convert all timestamps to Coordinated Universal Time (UTC) before storing them. This standardizes time representation, making it consistent regardless of the user's location. The article acknowledges that for optimal user experience, the API should be flexible enough to handle different time zones and presentation formats.

  5. API Flexibility: The article concludes by advocating for API flexibility. It suggests allowing users to specify time zones and formats when retrieving or entering timestamps. This flexibility extends to supporting different output formats, such as local time or UTC, and even providing Epoch time if needed.

In summary, the article takes developers through a journey of timestamp evolution, starting from naive timestamps to the adoption of more sophisticated solutions like Unix Epoch time and, ultimately, Coordinated Universal Time. It emphasizes the importance of flexibility in API design to accommodate diverse user preferences and requirements.

4 steps to returning a correct timestamp in an API (2024)


Top Articles
Latest Posts
Article information

Author: Tish Haag

Last Updated:

Views: 5464

Rating: 4.7 / 5 (47 voted)

Reviews: 94% of readers found this page helpful

Author information

Name: Tish Haag

Birthday: 1999-11-18

Address: 30256 Tara Expressway, Kutchburgh, VT 92892-0078

Phone: +4215847628708

Job: Internal Consulting Engineer

Hobby: Roller skating, Roller skating, Kayaking, Flying, Graffiti, Ghost hunting, scrapbook

Introduction: My name is Tish Haag, I am a excited, delightful, curious, beautiful, agreeable, enchanting, fancy person who loves writing and wants to share my knowledge and understanding with you.