api-guidelines icon indicating copy to clipboard operation
api-guidelines copied to clipboard

Add naming guidance to Azure API Guidelines

Open mikekistler opened this issue 3 years ago • 2 comments

Add guidance for naming of properties, parameters, etc to the Azure API Guidelines.

We can probably borrow some of the guidance the MS Graph team has written:

https://github.com/microsoft/api-guidelines/blob/vNext/graph/GuidelinesGraph.md#naming

mikekistler avatar Jun 14 '22 16:06 mikekistler

A few common ones come to mind re: dates e.g.,

  • createdOn
  • updatedOn
  • notBefore
  • expiresOn (often notAfter)
  • confidence/confidenceThreshold (drop "Score")

Some of these were discussed at length early on for our first track 2 GAs like Key Vault, but I think over time have been forgotten. Better to bake that into the swagger development process - or at least into the code gen / SDK review process.

heaths avatar Jun 23 '22 22:06 heaths

For Boolean naming, I like the guidance here

JeffreyRichter avatar Jul 19 '22 23:07 JeffreyRichter

This was addressed by #391

mikekistler avatar Feb 01 '23 19:02 mikekistler