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
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,5 @@
1
1
## Considerations for Service Design
2
-
Great APIs make your service usable to customers. They are intuitive, naturally reflecting and communicating the underlying model and its behavior. They lend themselves easily to client library implementations in multiple programming languages. And they don't "get in the way" of the developer, by remaining stable and predictable, <i>especially over time</i>.
2
+
Great APIs make your service usable to customers. They are intuitive, naturally reflecting and communicating the underlying model and its behavior. They lend themselves easily to client library implementations in multiple programming languages. And they don't "get in the way" of the developer, by remaining stable and predictable, _especially over time_.
3
3
4
4
This document provides Microsoft teams building Azure services with a set of guidelines that help service teams build great APIs. The guidelines create APIs that are approachable, sustainable, and consistent across the Azure platform. We do this by applying a common set of patterns and web standards to the design and development of the API. For developers, a well defined and constructed API enables them to build fault-tolerant applications that are easy to maintain, support, and grow. For Azure service teams, the API is often the source of code generation enabling a broad audience of developers across multiple languages.
5
5
@@ -11,7 +11,7 @@ It is critically important to design your service to avoid disrupting users as t
11
11
12
12
:white_check_mark:**DO** ensure that customer workloads never break
13
13
14
-
:white_check_mark:**DO** ensure that customers are able to adopt a new version of service or SDK client library <b>without requiring code changes</b>
14
+
:white_check_mark:**DO** ensure that customers are able to adopt a new version of service or SDK client library **without requiring code changes**
15
15
16
16
### Azure Management Plane vs Data Plane
17
17
*Note: Developing a new service requires the development of at least 1 (management plane) API and potentially one or more additional (data plane) APIs. When reviewing v1 service APIs, we see common advice provided during the review.*
@@ -42,7 +42,7 @@ The whole purpose of a preview to address feedback by improving abstractions, na
42
42
### Focus on Hero Scenarios
43
43
It is important to realize that writing an API is, in many cases, the easiest part of providing a delightful developer experience. There are a large number of downstream activities for each API, e.g. testing, documentation, client libraries, examples, blog posts, videos, and supporting customers in perpetuity. In fact, implementing an API is of miniscule cost compared to all the other downstream activities.
44
44
45
-
*For this reason, it is <b>much better</b> to ship with fewer features and only add new features over time as required by customers.*
45
+
*For this reason, it is **much better** to ship with fewer features and only add new features over time as required by customers.*
46
46
47
47
Focusing on hero scenarios reduces development, support, and maintenance costs; enables teams to align and reach consensus faster; and accelerates the time to delivery. A telltale sign of a service that has not focused on hero scenarios is "API drift," where endpoints are inconsistent, incomplete, or juxtaposed to one another.
0 commit comments