You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: azure/ConsiderationsForServiceDesign.md
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -88,7 +88,7 @@ As you build out your service and API, there are a number of decisions that can
88
88
89
89
Good names for resources, properties, operations, and parameters are essential to a good developer experience.
90
90
91
-
Resources are typically described by nouns. Resource and property names must be descriptive and easy to understand for end-users. Ease of understanding comes from familiarity and recognition; you should favor consistency with other Azure services, names in the productuser interface, and industry standards.
91
+
Resources are described by nouns. Resource and property names must be descriptive and easy for customers to understand. Ease of understanding comes from familiarity and recognition; you should favor consistency with other Azure services, names in the product's portal/user interface, and industry standards.
92
92
93
93
Names should aid developers in discovering functionality without having to constantly refer to documentation.
94
94
Use common patterns and standard conventions to aid developers in correctly guessing common property names and meanings.
@@ -107,11 +107,11 @@ The following are recommended naming conventions for Azure services:
107
107
108
108
For example, `nextUrl` and not `nextURL`.
109
109
110
-
:ballot_box_with_check:**YOU SHOULD** use "at" suffix in names of `date-time` values.
110
+
☑️**YOU SHOULD** use "At" suffix in names of `date-time` values.
111
111
112
112
:ballot_box_with_check:**YOU SHOULD** use "is" prefix in names of `boolean` values.
113
113
114
-
:ballot_box_with_check:**YOU SHOULD** use a suffix of the unit of measurement for values with a clear unit of measurement (such as bytes, miles, and so on). Use a generally accepted abbreviation for the units (e.g. "km" rather than "kilometers") when appropriate.
114
+
☑️**YOU SHOULD** use a suffix of the unit of measurement for values with a clear unit of measurement (such as bytes, miles, and so on). Use a generally accepted abbreviation for the units (e.g. "Km" rather than "Kilometers") when appropriate.
115
115
116
116
:ballot_box_with_check:**YOU SHOULD** use an int for time durations and include the time units in the name.
117
117
@@ -121,7 +121,7 @@ For example, `expirationDays` as `int` and not `expiration` as `date-time`.
121
121
122
122
:warning:**YOU SHOULD NOT** use brand names in resource or property names.
123
123
124
-
:warning:**YOU SHOULD NOT** use acronyms or abbreviations unless they are broadly understood.
124
+
⚠️**YOU SHOULD NOT** use acronyms or abbreviations unless they are broadly understood for example, "ID" or "URL", but not "Num" for "number".
125
125
126
126
:no_entry:**DO NOT** use redundant words in names.
127
127
@@ -141,7 +141,7 @@ The following are recommended names for properties that match the associated des
141
141
142
142
### `name` vs `id`
143
143
144
-
The identifier of a resource should be named `id`. This holds even in the case where the identifier is assigned by the user with a PUT method.
144
+
The identifier of a resource should be suffixed with `Id`. This holds even in the case where the identifier is assigned by the user with a PUT/PATCH method.
145
145
146
146
## Use Previews to Iterate
147
147
Before releasing your API plan to invest significant design effort, get customer feedback, & iterate through multiple preview releases. This is especially important for V1 as it establishes the abstractions and patterns that developers will use to interact with your service.
0 commit comments