search

microsoft / api-guidelines

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

Clarification on Microsoft and Azure guideline conflict on naming date time properties #451

Closed TimLovellSmith closed 1 year ago

TimLovellSmith commented 1 year ago

They seem very much in conflict on the topic of ‘createdAt’ vs ‘createdDateTime’, 'lastModifiedAt' vs 'lastModifiedDateTime', 'expiresAt' vs 'expirationDateTime' etc. And the MS guideline is stated as MUST.

Is it deliberate?

api-guidelines/Guidelines.md at vNext · microsoft/api-guidelines (github.com)

api-guidelines/ConsiderationsForServiceDesign.md at vNext · microsoft/api-guidelines · GitHub

JeffreyRichter commented 1 year ago

The OLD guidelines you refer to (1st link you put in your comment) are woefully out of date and have a big notice at the top stating that they should not be used.

Yes, we deliberately changed the guidance around (not) using DateTime. One reason for the change is because DateTime is very .NET-ish and is not what is used by other languages, and we want Azure REST APIs to be language agnostic to not turn off developers using any language. In addition, the old guidance was not used consistently across Azure services (we researched this) and so it wasn't followed well. "At" was also used pretty heavily and so we went with "At".

TimLovellSmith commented 1 year ago

@JeffreyRichter Thanks for pointing out the big warning that I was overlooking. :)