Skip to content

Commit 8af7be8

Browse files
authored
Merge pull request #416 from microsoft/markweitzel-armlink
Update Guidelines.md
2 parents 64212e0 + 102e8d3 commit 8af7be8

File tree

1 file changed

+3
-6
lines changed

1 file changed

+3
-6
lines changed

azure/Guidelines.md

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,20 +26,17 @@ Please ensure that you add an anchor tag to any new guidelines that you add and
2626

2727
## Introduction
2828

29-
These guidelines offer prescriptive guidance that Azure service teams MUST follow ensuring that customers have a great experience by designing APIs meeting these goals:
29+
These guidelines apply to Azure service teams implementing _data plane_ APIs. They offer prescriptive guidance that Azure service teams MUST follow ensuring that customers have a great experience by designing APIs meeting these goals:
3030
- Developer friendly via consistent patterns & web standards (HTTP, REST, JSON)
3131
- Efficient & cost-effective
3232
- Work well with SDKs in many programming languages
3333
- Customers can create fault-tolerant apps by supporting retries/idempotency/optimistic concurrency
3434
- Sustainable & versionable via clear API contracts with 2 requirements:
3535
1. Customer workloads must never break due to a service change
3636
2. Customers can adopt a version without requiring code changes
37+
Technology and software is constantly changing and evolving, and as such, this is intended to be a living document. [Open an issue](https://github.com/microsoft/api-guidelines/issues/new/choose) to suggest a change or propose a new idea. Please read the [Considerations for Service Design](./ConsiderationsForServiceDesign.md) for an introduction to the topic of API design for Azure services. *For an existing GA'd service, don't change/break its existing API; instead, leverage these concepts for future APIs while prioritizing consistency within your existing service.*
3738

38-
Technology and software is constantly changing and evolving, and as such, this is intended to be a living document. [Open an issue](https://github.com/microsoft/api-guidelines/issues/new/choose) to suggest a change or propose a new idea.
39-
40-
See the [Considerations for Service Design](./ConsiderationsForServiceDesign.md) for an introduction to the topic of API design for Azure services.
41-
42-
*NOTE: For an existing GA'd service, don't change/break its existing API; instead, leverage these concepts for future APIs while prioritizing consistency within your existing service.*
39+
*Note: If you are creating a management plane (ARM) API, please refer to the [Azure Resource Manager Resource Provider Contract](https://github.com/Azure/azure-resource-manager-rpc).*
4340

4441
### Prescriptive Guidance
4542
This document offers prescriptive guidance labeled as follows:

0 commit comments

Comments
 (0)