Challenges in handling date and time in REST API and distributed web applications

One of the important thing we addressed in BizTalk360 version 7.8 (releasing Oct, 2014) is a mechanism to have consistent date and time handling. Handling date and time consistently may sound very obvious one, but it’s pretty hard to get it right if you haven’t done it correctly in the early stages of the project. The impact is everywhere in each layer (front-end, service API’s and database). We delayed addressing this problem for a while due to sheer complexity in this task, finally we took the plunge and sorted it in version 7.8. We are introducing a new concept called user profile and giving the flexibility for the users to select their preferred time zone as well as date/time format string.

What is the challenge?

We have wide variety of customer base and one of the classic scenario is shown in the below picture.

The customer’s main business is out of USA and their BizTalk environment and BizTalk360 (servers) are hosted in New York. The customer is a multi national corporation (MNC) and they have their employees spread across multiple countries (ex: India, Germany and USA). In the previous versions of BizTalk360 (prior to 7.8), in this scenario, when the users access any screens that contains some date/time values (example: Message Box Queries), the date/time will be displayed based on the server time zone (NewYork) and format of the date/time string will be based on the users browser setting (ex: 10/28/2014 09:00:00 for USA and 28/10/2014 09:00:00 for UK).

As such it’s not a big problem, but a small limitation in the product. Things were pretty good at the early stages of BizTalk360 when our front end was Silverlight. We used SOAP based WCF services and Silverlight applications were able to do a proper service reference and create typed object for the server side classes. All our input/output date and time parameters to WCF services were properly typed (ex: .NET DateTime object). We also didn’t get into the issues of browser war, since Silverlight creates a sand boxed infrastructure and it’s .NET on both server and client side.

But when we switched to HTML5 in BizTalk360 version 7.0 last year, things start to fall apart in few places when it comes to date and time. There are quite lot of changes technically, our SOAP based WCF services turned into JSON based service, and the client side changed from Silverlight to JavaScript with bunch of open-source frameworks. All of the sudden we lost the Silverlight sandbox infrastructure and type safety. Now everything is “STRING“.

Converting date and time string value back and forth between multiple technologies (JavaScript, .NET) normally causes headaches until you clear it in the right way. That’s exactly what we have done in 7.8

Introduction to user profile

Until this point we didn’t have the notion of user profile. BizTalk360 uses windows authentication and the standard active directory. Apart from the windows account name and the AD groups they belong to, we didn’t have any other user preference (profile information) stored in BizTalk360. If you look at the scenario above, the ideal solution will be for people in India to set their preference. Whether they wanted the date and time value to show as New York time or India time (similarly for other country employees). That’s exactly what we have done in 7.8 by introducing the concept of user profile. The user can specify his/her preferred time zone and date/time display format in the profile, and the entire system will perform according to the user selection.

Let’s get bit more technical

Now let’s see the technical implementation behind the scene. At the very high level the architecture looks as shown in the below picture, showing what date time format is passed between different layers. The most important point here is, when you are dealing with JSON it’s all text (STRING) and it’s important you agree a contract between your front-end web and back-end service what format the date and time is going to be represented. Apply another hard rule of thumb, any data that gets into database is going to be in UTC format.

You must apply some hard core rules between multiple layers

Database: Everything that goes in and out is going to be UTC

Server REST API: Everything that goes in and out is going to be UTC

The client (front-end) : Everything that goes in and out is going to be UTC

All the above rules looks the same, so where is the trick? There are couple of important tricks here

The format string of the UTC date and time value passed between the REST API and the front-end web, and

The availability of user profile data to the front-end (using a separate call).

If you look carefully we kind of created a shield for ourselves, not relying on browser settings and server time zone settings. Everything is precise and controlled by the user preference.

Let’s talk about UTC date and time string format

Out of the 2 important tricks we applied, one of the trick is agreeing on the standard date and time format string between the client and REST API. It’s a simple no brainer decision to use the ISO-8601 format, it’s pretty much THE internet standard when it comes to handling date and time in web focused applications. If you look at the JSON messages going backwards and forwards between the client and REST API, the format of the date and time string will be ISO-8601 as shown below.

There are lot of flexibility in the ISO-8601 format for example we could have easily replaced the “Z” at the end with a proper time zone offset like -0530 (India). Again it comes down to agreeing on a solid contract between the client and server API so that they both know what to except from each layers.

Now everything looks pretty simple and straight forward, if you have done this procedure right at the beginning of the project, then its very simple. But if you wanted to fix it after sometime, it will be a time consuming process. It took us 3 months effort to sort this problem, since it required lot of impact analysis in all layers. We are very glad to sort this out for good now.

Author: Saravana Kumar

Saravana Kumar is the Founder and CTO of BizTalk360, an enterprise software that acts as an all-in-one solution for better administration, operation, support and monitoring of Microsoft BizTalk Server environments.
View all posts by Saravana Kumar