Please use standard date formats in your API

  • 2
  • Idea
  • Updated 5 years ago
The JSON response from your API includes some fairly strange date formatting:

"date": {

"pretty": "April 5, 2006",
"year": "2006",
"mon": "04",
"mday": "05",
"hour": "12",
"min": "00",
"tzname": "America/Los_Angeles"
},
"utcdate": {
"pretty": "April 5, 2006",
"year": "2006",
"mon": "04",
"mday": "05",
"hour": "19",
"min": "00",
"tzname": "UTC"
}


I understand you were probably trying to be verbose, but this is a bit over the top. It actually makes it very difficult to consume properly.

While JSON has no specific date/time specification, the developer community at large has embraced the ISO-8601 standard - which is highly appropriate here. The above output should be written like this instead:

"date": "2006-04-05T12:00:00-07:00",

"tzname": "America/Los_Angeles"


A few points:

  • "pretty" output should be omitted. Your idea of pretty will vary quite wildly from someone else's. The world is a big place, and there are many different languages and date/time formats. Just about every language and platform has its own way to handle date/time formatting. Sometimes it's built in, and sometimes you might use a library, such as moment.js for JavaScript.

  • There's no need to provide two different copies of the date, local and UTC. Just use the local time, with the UTC offset. This is fully understood and supported by the ISO8601 spec. It gives the correct local time, and you can use the offset to calculate the UTC time if desired.

  • The time zone name is great - thanks for using IANA/Olson standard time zones. But they are much easier consumed if you just supply it in its own property, rather than bundled inside the same object as the date. Then when you have multiple dates to show (such as in your history api), you can move the time zone outside of the array. As long as the location is the same, the time zone only needs to appear once.

  • Also keep in mind that by itself your current "date" object has a problem with ambiguity of local dates during a daylight saving time fall-back transition. This can be resolved since you typically provide UTC also - but that does make it difficult to write an accurate deserializer for the date type by itself. Switching to the ISO8601 extended format with an offset supplied will resolve this issue also.



Aside - I don't really do a lot with weather APIs, but I do a ton with date/time. I was pointed over here while answering a question on StackOverflow, where I spend a lot of time answering questions about date, time and time zones, and occasionally about JSON serialization in .NET. Please take my advice here as suggestions for improvements to your API that you might incorporate into a future revision. Thanks.
Photo of MattJohnson

MattJohnson

  • 1 Post
  • 0 Reply Likes

Posted 5 years ago

  • 2
Photo of Brendan Hayes

Brendan Hayes, Official Rep

  • 962 Posts
  • 123 Reply Likes
Oh I know, its a bit lame. In new versions and features we are going to clean up and standardize this.
Photo of Brendan Hayes

Brendan Hayes, Official Rep

  • 962 Posts
  • 123 Reply Likes
ps: one of our developers says we should do EXACTLY this. Thank you for your thoughtful post!