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
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -89,8 +89,8 @@ As you build out your service and API, there are a number of decisions that can
89
89
Good names for resources, properties, operations, and parameters are essential to a great developer experience.
90
90
91
91
Resources are described by nouns. Resource and property names must be descriptive and easy for customers to understand.
92
-
Avoid names that refer to service implementation details, e.g. "TreeLeafNode", or simply describe the structure of value without
93
-
describing its purpose, e.g. "KeyValuePair".
92
+
Use names that correspond to user scenarios rather than service implementation details, e.g. "Diagnosis" and not "TreeLeafNode".
93
+
Names should convey the value's purpose and not simply describe its structure, e.g. "ConfigurationSetting" and not "KeyValuePair".
94
94
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.
95
95
96
96
Names should aid developers in discovering functionality without having to constantly refer to documentation.
@@ -128,7 +128,7 @@ For example, `expirationDays` as `int` and not `expiration` as `date-time`.
128
128
129
129
:warning:**YOU SHOULD NOT** use names that are reserved words in widely used programming languages (including C#, Java, JavaScript/TypeScript, Python, C++, and Go).
130
130
131
-
:no_entry:**DO NOT** use "is" prefix in names of `boolean` values.
131
+
:no_entry:**DO NOT** use "is" prefix in names of `boolean` values, e.g. "enabled" not "isEnabled".
132
132
133
133
:no_entry:**DO NOT** use redundant words in names.
134
134
@@ -167,7 +167,7 @@ Before releasing your API plan to invest significant design effort, get customer
167
167
As your service evolves over time, it will be natural that you want to remove operations that are no longer needed. For example, additional requirements or new capability in your service, may have resulted in a new operation that, effectively, replaces an old one.
168
168
Azure has a well established breaking changes policy that describes how to approach these kinds of changes. As part of this policy, the service team is required to clearly communicate to customers when their API is changing, e.g. deprecating operations. Often, this is done via an email to the address that is attached to the Azure subscription.
169
169
170
-
However, given how many organizations are structured, it's common that this email address is different from the actual people writing code against your API. To address this, the service API should declare that it may return the `azure-deprecating` header, to indicate that this operation will be removed in the future. There is a simple string convention, specied in the [Azure REST API Guidelines](https://aka.ms/azapi/guidelines) that provides more information about the forthcoming deprecation.
170
+
However, given how many organizations are structured, it's common that this email address is different from the actual people writing code against your API. To address this, the service API should declare that it may return the `azure-deprecating` header, to indicate that this operation will be removed in the future. There is a simple string convention, specifed in the [Azure REST API Guidelines](https://aka.ms/azapi/guidelines) that provides more information about the forthcoming deprecation.
171
171
This header is targeted at developers or operation professionals, and it is intended to give them enough information and lead time to properly adapt to this change. Your documentation should reference this header and encourage logging and alerting practices based on its presence.
0 commit comments