Merge remote-tracking branch 'origin/vnext' into graph

darrelmiller · darrelmiller · commit 7a038b68ce69 · 2022-02-18T17:05:59.000-05:00
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -0,0 +1,2 @@
+# These are the set of folks who should review PRs on the azureRestUpdates branch.
+* @microsoft/azure-api-stewardship-board
diff --git a/README.md b/README.md
@@ -6,6 +6,9 @@ They may additionally create documents specific to their team, adding further gu
 We publish these guidelines here with the aim of fostering dialogue and learning in the API community at large.
 We further hope that these guidelines may encourage other organizations to create guidelines that are appropriate for them and in turn, if they are able, to publish theirs.
 
+### Additional guidance for Azure service teams
+Azure service teams should reference the companion documents, [Azure REST API Guidelines](./azure/Guidelines.md) and [Considerations for Service Design](./azure/ConsiderationsForServiceDesign.md), when building or modifying their services. These documents provide a refined set of guidance targeted specifically for Azure services. For more information please refer to the [README](./azure/README.md) in the Azure folder. 
+
 [![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/)
 
 ## Code of Conduct
diff --git a/azure/.markdownlint.json b/azure/.markdownlint.json
@@ -0,0 +1,16 @@
+{
+  "default": true,
+  "MD012": {
+    "maximum": 2
+  },
+  "MD013": {
+    "line_length": 500
+  },
+  "MD022": false,
+  "MD031": false,
+  "MD032": false,
+  "MD033": {
+    "allowed_elements": [ "sup" ]
+  },
+  "MD036": false
+}
diff --git a/azure/ConsiderationsForServiceDesign.md b/azure/ConsiderationsForServiceDesign.md
diff --git a/azure/Guidelines.md b/azure/Guidelines.md
diff --git a/azure/README.md b/azure/README.md
@@ -0,0 +1,12 @@
+# Azure REST API Guidance
+When building software components that will be used by developers to build other software, providing APIs that are easy to use, fit to purpose, scalable, maintainable, and consistent across your product can make the difference between success and failure for your software. 
+
+Designing powerful APIs with strong defaults, consistent behavior across related projects, and ease of use for developers arises from putting yourself in the shoes of the person using your interfaces, and taking their concerns to heart. The APIs you ship can have a dramatic long term effect on the health of your software product, and that is why the **REST API Stewardship Board** is here to help! We have published a collection of best practices, REST guidance, and OpenAPI style guidelines to help you create an amazing developer experience.
+* [Considerations for Service Design](ConsiderationsForServiceDesign.md)
+* [REST API Guidelines](Guidelines.md)
+* [OpenAPI Style Guidelines](https://github.com/Azure/azure-api-style-guide/blob/main/README.md)
+* [Breaking Changes](http://aka.ms/AzBreakingChangesPolicy/)
+
+You can reach out to use via [email](mailto://azureapirbcore@microsoft.com) or in our [Teams](https://teams.microsoft.com/l/team/19%3a3ebb18fded0e47938f998e196a52952f%40thread.tacv2/conversations?groupId=1a10b50c-e870-4fe0-8483-bf5542a8d2d8&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47) channel.
+
+<sub>Note: The Teams channel is internal MS.</sup>
diff --git a/azure/relo.drawio b/azure/relo.drawio
@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2021-09-11T13:44:17.217Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/93.0.4577.63 Safari/537.36" etag="t4f5ABaeVZXpi9mlGWUy" version="15.1.4" type="device"><diagram id="kgpKYQtTHZ0yAKxKKP6v" name="Page-1">5VhbV6MwGPw1POqBBGj7aFutD7vas8WjPkaIkCMlbBpsu79+g4RLSKW37e6qL20zhA8yM9+QYsDRfDVhKI2+0wDHBjCDlQHHBgAugOIzB9YFYNv9AggZCQrIqoEZ+YUlaEo0IwFeKBM5pTEnqQr6NEmwzxUMMUaX6rRnGqtXTVGINWDmo1hH70nAowLtO2aNX2MSRuWVLVMemaNysgQWEQrosgHBSwOOGKW8+DVfjXCcc1fyUpx39c7R6sYYTvguJ8AkG16t2MBffzPT5PbeA2hyJsV4RXEmFzy980SN6YU3us6/b2eevH2+Ljl5xYwTQdFFTMJEQE+Uczo34BAnwUXOeY7F1H8RULVqMx9wRl8qHi2BPNOES9EtwchQX5RcJw4UneQSJ5jOMWdrMYHhGHHyqsqGpPphNa86dUqJuAQwpVEtKGWSPrVcUy2xoBnzsTyrSXOrkG1vKcQRCzHXCokfjfXU0JuKeyg60BS99rypQEDuTFHT/IGLtRiOEATxrLgv92eWO3E4ZdTHiwVJwhoznPGXMIGm3QAcZgLNTe1Cf84Ek7u4P/UGmZ0CAm8eQkL5zZmlmWAUEyyv1VSR0SwJcCCFWEaE41mK/PzoUuS5wCI+jzfo5HTplHsDrzqVkkd7lsLTQNK2rKO2CtSoEbPQfF9ahct9ibM14jTKGv5OaCLAYYAWUcVhB1+CJrZ+yNvgvBo+yrlvg/FK9kgxWm/smM4OKXy13RlbO6mhgLNBgBI7NnWBqj/sHZi60FULaQ45ccP1tvsmFL2W7t4y1ZYGPZUVzM1SleFlqpmzay+B/qmaCWqkVI+eE+dQp0bbw+mfxY/zUeOni/D/JGvs/rmjZkTb+Dtv8dqV/nLY6Jv2yeUH2aWXcd3Kqt7R+3UArQPFtLcUOrGYX3q//o4dnN7ezd1W0e0dZgfNV+1Cp965m5+uuS2743G5mwpVyWO7Wyt0ajn1f2L7tfcs832M863Rp+luC7jHtjeE7mF+0IzVLnSwH8SwfpdXTK9fiMLL3w==</diagram></mxfile>
diff --git a/azure/relo.jpg b/azure/relo.jpg
diff --git a/azure/statmon.drawio b/azure/statmon.drawio
@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2021-09-11T12:13:51.175Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/93.0.4577.63 Safari/537.36" etag="qdiZw4AkgMOWKiVPrqxd" version="14.9.9" type="device"><diagram id="kgpKYQtTHZ0yAKxKKP6v" name="Page-1">5Vhrc6IwFP01fHSHEB760Qe1O305xU7bjyxEYIsJG0PV/voNEnnF+traqd12piWH5GLOOTf3igL708WQukl4Q3wUK5rqLxQ4UDTNggb/mwHLHDBUAQQ08nMIlIATvSEBqgJNIx/NahMZITGLkjroEYyRx2qYSymZ16dNSFx/auIGSAIcz41l9DHyWZijbUMt8UsUBeH6yUAVd6buerIAZqHrk3kFgrYC+5QQll9NF30UZ9ytecnXXbxzt/hgFGG2zwKI097Fgna85bWa4LvHseYOW+08yqsbp2LDo4cxjzHqjvuX2f87JxsO7Gt7bIt9sOWanFdEWcS56sZRgDn0izBGpgrsIex3M/IzLCbeC4eK7avZgFHyUhAKODIhmAn1AaemJ+9ObBj5NcHEXoeITBGjSz6Bothl0WtdP1fYICjmFUtHJOKP0FThWGAJgwrDAlP9oVZ+GgFnJKUeEjGq7DfC6lBthq0HYi4NEJMC8YvK7kpoJe4BQnckoS/H4xFH+K+imYoGQSbMXYIoZ4/gFpdtdbGabMZchJ7DXJbO+JobgiNGKL96uL/mdwO2UqyIcp992JY7YYhWlmNcTv0PjNRUXAP6cdYB1o5AH2ed4UPcHo07qZ5oEbx9CiLCbltAsk4/jpB4VlVFSlLsI18IMQ8jhpzE9bK7c14cOBayabxBJ2ObTpk30GKrUuu7oE5URwzn5cFdHM9h5dCG6vva1sg8lDldYk7irGJwTDAHe747CwsStxDGeaLLpywPfhTDZzF3NRgsRJLko+XGlNmaIrmxdltjZypVFDA2CLDG/vXoNuv6w7Zx5GHdMJLkkBNnnFyVh/b4PA7NxTqlGuVOhQer2W6IYMKPKMRm81g24adqu6UQ8w/GY6qKxRVaVdpV7fyTZh1ib0SJh2azCAclpliDfMn3KLjveKeZxbutI2ncOfIgkEpvM9CJzQIls3RHPzlgYz8pnvmVSjBsd75WCTbOvATvnTQdUCfekojfVnkPaGv1HbVx7yLbCAQ061S5dTWnb1cvfeeZQhvc/GbTyZOzoa2Vv998sewy2ubO7AInyq6NHGrfPbs+p3E19Q9qXJuBgHayxnWjH+R6dfaNq6UfqmazcYVQP0XjysN+qrbyl9n9Glcn9TyEsmOz3reesymaL+8Ob0mhdWTZbLakUqCjbcCH5dvofHr5Sh/afwE=</diagram></mxfile>
diff --git a/azure/statmon.jpg b/azure/statmon.jpg
diff --git a/graph/patterns/dictionary-client-guidance.md b/graph/patterns/dictionary-client-guidance.md
@@ -15,12 +15,12 @@ In **components** in  **schemas**:
 ```json
 {
   "roleSettings": {
-    "type": "object", 
+    "type": "object",
       "properties": {
-        "domain": { 
-          "type": "string" 
-        } 
-      } 
+        "domain": {
+          "type": "string"
+        }
+      }
     }
   }
 }
@@ -30,7 +30,7 @@ In **components** in  **schemas**:
 {
   "type": "object",
   "patternProperties": {
-    ".*": { 
+    ".*": {
       "$ref": "#/components/schemas/roleSettings"
     },
     "additionalProperties": false
@@ -40,11 +40,11 @@ In **components** in  **schemas**:
 
 ## SDK Support
 
-SDKs need to provide support for dictionary types so SDK consummers get a delightful development experience. Examples are provided below for different languages. Other aspects need to be taken into considerations:
+SDKs need to provide support for dictionary types so SDK consumers get a delightful development experience. Examples are provided below for different languages. Other aspects need to be taken into considerations:
 
 - Dictionaries support OData annotations (values prefixed with **@OData**), such annotations should not be inserted directly in the dictionary but rather in the additional properties manager.
 - Dictionary types can inherit another dictionary type, this inheritance must be respected.
-- Dictionary values can be of union types, if the target langauge doesn't support union types, a wrapper type should be generated as backward compatible solution with properties for each type of the union.
+- Dictionary values can be of union types, if the target language doesn't support union types, a wrapper type should be generated as backward compatible solution with properties for each type of the union.
 
 ### Dotnet
 
@@ -74,6 +74,6 @@ or
 
 ## Request builder generation annotation
 
-By default SDKs are not required to contain a set of request builders to run CRUD requests on entries in the dictionary. The dictionary will be updated as a whole by consummers by sending requests to the parent entity.
+By default SDKs are not required to contain a set of request builders to run CRUD requests on entries in the dictionary. The dictionary will be updated as a whole by consumers by sending requests to the parent entity.
 
-If a **SupportedHttpMethod** annotation is specified for the dictionary type, request builders should be generated to allow consummers to automically update the entries.
+If a **SupportedHttpMethod** annotation is specified for the dictionary type, request builders should be generated to allow consumers to automatically update the entries.
diff --git a/graph/patterns/dictionary.md b/graph/patterns/dictionary.md
@@ -52,7 +52,7 @@ Before using a dictionary type in your API definition make sure your scenario fi
 
 ### JSON payload example
 
-The following example illustrates the resulting JSON for a property of dictionary type. The parent object has been ommitted for brievety.
+The following example illustrates the resulting JSON for a property of dictionary type. The parent object has been omitted for brevity.
 
 ```json
 {
@@ -78,7 +78,7 @@ In this set of examples we're modeling a **roles** property of dictionary type o
 GET https://graph.microsoft.com/v1.0/users/10/roles/author
 ```
 
-Reponse:
+Response:
 
 ```json
 {
@@ -92,7 +92,7 @@ Reponse:
 GET https://graph.microsoft.com/v1.0/users/10/roles
 ```
 
-Reponse:
+Response:
 
 ```json
 {
@@ -114,7 +114,7 @@ Reponse:
 GET https://graph.microsoft.com/v1.0/users/10
 ```
 
-Reponse:
+Response:
 
 ```json
 {
@@ -164,7 +164,7 @@ PATCH https://graph.microsoft.com/v1.0/users/10/roles
 ```
 
 > Note: setting one of the keys to **null** deletes it from the dictionary.
-> Note: the domain values for the existing author and maintainer entries will get udpated.
+> Note: the domain values for the existing author and maintainer entries will get updated.
 > Note: the reviewer entry will be inserted in the dictionary.
 
 #### Updating an entry in the dictionary
@@ -202,7 +202,7 @@ The following example defines a complex type **roleSettings** as well as a dicti
     </Collection>
   </Annotation>
   <Annotation Term="SupportedHttpMethod">
-    <Collection><!-- use this annotation to indicate you want the SDKs to generate additional request builders to update the dictionary atomtically -->
+    <Collection><!-- use this annotation to indicate you want the SDKs to generate additional request builders to update the dictionary automatically -->
       <String>GET</String>
       <String>PATCH</String>
       <String>DELETE</String>

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+# These are the set of folks who should review PRs on the azureRestUpdates branch.`
	`2`	`+* @microsoft/azure-api-stewardship-board`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+<mxfile host="app.diagrams.net" modified="2021-09-11T13:44:17.217Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/93.0.4577.63 Safari/537.36" etag="t4f5ABaeVZXpi9mlGWUy" version="15.1.4" type="device"><diagram id="kgpKYQtTHZ0yAKxKKP6v" name="Page-1">5VhbV6MwGPw1POqBBGj7aFutD7vas8WjPkaIkCMlbBpsu79+g4RLSKW37e6qL20zhA8yM9+QYsDRfDVhKI2+0wDHBjCDlQHHBgAugOIzB9YFYNv9AggZCQrIqoEZ+YUlaEo0IwFeKBM5pTEnqQr6NEmwzxUMMUaX6rRnGqtXTVGINWDmo1hH70nAowLtO2aNX2MSRuWVLVMemaNysgQWEQrosgHBSwOOGKW8+DVfjXCcc1fyUpx39c7R6sYYTvguJ8AkG16t2MBffzPT5PbeA2hyJsV4RXEmFzy980SN6YU3us6/b2eevH2+Ljl5xYwTQdFFTMJEQE+Uczo34BAnwUXOeY7F1H8RULVqMx9wRl8qHi2BPNOES9EtwchQX5RcJw4UneQSJ5jOMWdrMYHhGHHyqsqGpPphNa86dUqJuAQwpVEtKGWSPrVcUy2xoBnzsTyrSXOrkG1vKcQRCzHXCokfjfXU0JuKeyg60BS99rypQEDuTFHT/IGLtRiOEATxrLgv92eWO3E4ZdTHiwVJwhoznPGXMIGm3QAcZgLNTe1Cf84Ek7u4P/UGmZ0CAm8eQkL5zZmlmWAUEyyv1VSR0SwJcCCFWEaE41mK/PzoUuS5wCI+jzfo5HTplHsDrzqVkkd7lsLTQNK2rKO2CtSoEbPQfF9ahct9ibM14jTKGv5OaCLAYYAWUcVhB1+CJrZ+yNvgvBo+yrlvg/FK9kgxWm/smM4OKXy13RlbO6mhgLNBgBI7NnWBqj/sHZi60FULaQ45ccP1tvsmFL2W7t4y1ZYGPZUVzM1SleFlqpmzay+B/qmaCWqkVI+eE+dQp0bbw+mfxY/zUeOni/D/JGvs/rmjZkTb+Dtv8dqV/nLY6Jv2yeUH2aWXcd3Kqt7R+3UArQPFtLcUOrGYX3q//o4dnN7ezd1W0e0dZgfNV+1Cp965m5+uuS2743G5mwpVyWO7Wyt0ajn1f2L7tfcs832M863Rp+luC7jHtjeE7mF+0IzVLnSwH8SwfpdXTK9fiMLL3w==</diagram></mxfile>