search

microsoft / api-guidelines

Microsoft REST API Guidelines
Other
22.8k stars 2.71k forks source link

Add guidance on the format for time duration values #335

Open mikekistler opened 2 years ago

mikekistler commented 2 years ago

In particular, don't use the ISO 8601 duration format because it is poorly supported in language runtimes.

We should have guidance something like:

Consider not using ISO8601 durations in the PXX format because there's not great support or understanding (on things like selector's ttl). Instead pick a granularity (seconds, minutes, hours, ?) and allow people to define the number of those units for ttl.

heaths commented 2 years ago

I would at least extend the samples - your ? in the block comment - to include "days, months, years" to solve the anniversary problem. Rotating keys every 3 months (P3M) or certificates every year (P1Y) or two (P2Y) are very common scenarios. I would hope that people wouldn't get the impression they could or should only support something like "365 days" when that is insufficient.