Introducing DateTime Support and ISO 8601 Dates
Tags: javascript, webdev, programming, appwrite
Published: 2022-09-14 13:14:03

In Appwrite 1.0, we’re introducing a lot of new features. Among them is one of our most frequently requested features, DateTime support. Appwrite Databases now provides a dedicated DateTime attribute for storing date and time information. All Appwrite endpoints will also now return timestamps that are in DateTime format following [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) specification.

First time hearing about [Appwrite](https://appwrite.io/)? Appwrite is an open-source backend-as-a-service that abstracts all the complexity involved in building a modern application by providing you with a set of REST APIs for your core backend needs. Appwrite handles user authentication and authorization, real-time databases, cloud functions, webhooks, and much more!

## Common DateTime Representations
There are two main representations of storing date and time in computing, [Unix Time](https://en.wikipedia.org/wiki/Unix_time) and [DateTime](https://en.wikipedia.org/wiki/ISO_8601). 

Unix Time, also known as Epoch time or Posix time, stores time since Unix Epoch on January 1, 1970 at midnight UTC. Unix Time is expressed and stored as a 32 bit integer. 

DateTime stores time as a string. The format of the string is human readable, expressing year, month, date, hour, seconds, and milliseconds. For example, `2022-08-17T00:00:00`, which is the **Midnight of August 17th, 2022 in UTC**. 

The advantage of using Unix Time is that it’s stored as an integer. This makes Unix Time easier to store, query, and sort. A 32 bit integer takes up less space than a DateTime string and is less computationally intensive to do comparisons and arithmetic with. Unix Time is also independent of timezones, making it perfect for representing time on the web. 

The downside to Unix Time is that it’s not easily human readable and limited in date range. Unix Time cannot store time before 1970 or after 2038, which is very limiting.

DateTime following ISO 8601 is highly readable by a human and the default storage format for JSON. The potential downside of DateTime is that it can be timezone ambiguous and somewhat expensive to store and sort.

## Why DateTime?
Supporting DateTime attribute is one of the most frequently requested features we receive. The upsides of being highly readable by humans and being more flexible is highly valued to many Appwrite developers. 

We also decided to use DateTime for Appwrite’s response objects because it’s the default format provided by JavaScript’s `Date()` object. This helps us stay consistent.

To remove timezone ambiguity, Appwrite will handle and store all DateTime in UTC timezone. Unix Timestamps are still supported by Appwrite's Databases Service through 32 bit integers.

## Examples
Most languages will support both DateTime following ISO 8601 and Unix Timestamps in their system library. I’ll take JavaScript as an example to show you how to manipulate DateTime strings.


To create a datetime string of the current time in UTC:
```js
// Gets current date and time in UTC
var date = new Date(Date.now());

// Print current date and time in UTC
console.log(date.toISOString()) 
```


Just as easily, you can parse a UTC DateTime string. 

```js
// A DateTime string in UTC, converted to date object
const date = new Date('2022-08-24T20:41:21.909Z');
console.log(date.toISOString());
```


Notice that the dateTime string will have a `Z` at the end to denote UTC. When Javascript parses this string, it will automatically convert it to your machine’s timezone.


## Conclusions
One of the biggest benefits of building open source software in full publicity is the real-time feedback we receive from the community. It allows us to hear more voices and iterate faster. 


This new feature was the result of many suggestions and discussions on GitHub. I wanted to shout out those who pitched this idea to us time and time again:

- [Discussion #2944](https://github.com/appwrite/appwrite/discussions/2944)
- [Discussion #2909](https://github.com/appwrite/appwrite/discussions/2909)
- [Discussion #2451](https://github.com/appwrite/appwrite/discussions/2451#discussioncomment-1760684)
- [Issue #3018](https://github.com/appwrite/appwrite/issues/3018)

Your feedback is as valuable as code contributions and we encourage readers to pitch your thoughts to us. 

- 📝 [Appwrite GitHub Discussions](https://github.com/appwrite/appwrite/discussions)
- 🚀 [Appwrite Github](https://github.com/appwrite)
- 📜 [Appwrite Docs](https://appwrite.io/docs)
- 💬 [Discord Community](https://appwrite.io/discord)