Merge pull request #408 from microsoft/InfoTextInGuidelines

markweitzel · web-flow · commit 342208d9b97e · 2022-10-19T13:17:15.000-04:00
Updated guidelines to ref Azure &amp; Graph guidelines
diff --git a/Guidelines.md b/Guidelines.md
@@ -20,137 +20,157 @@ To provide the smoothest possible experience for developers on platforms followi
 
 This document establishes the guidelines Microsoft REST APIs SHOULD follow so RESTful interfaces are developed consistently.
 
+### **Guidance for Azure service teams**
+Azure service teams should use 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.
+
+### **Guidance for Microsoft Graph service teams**
+Graph service teams should reference the companion document, [Graph REST API Guidelines](./graph/GuidelinesGraph.md) when building or modifying their services. This document and the associated pattern catalog provides a refined set of guidance targeted specifically for Microsoft Graph services.
+
+
 ## 2. Table of contents
 <!-- TOC depthFrom:2 depthTo:4 orderedList:false updateOnSave:false withLinks:true -->
 
-- [Microsoft REST API Guidelines Working Group](#microsoft-rest-api-guidelines-working-group)
-- [1. Abstract](#1-abstract)
-- [2. Table of contents](#2-table-of-contents)
-- [3. Introduction](#3-introduction)
+- [Microsoft REST API Guidelines](#microsoft-rest-api-guidelines)
+  - [Microsoft REST API Guidelines Working Group](#microsoft-rest-api-guidelines-working-group)
+- [Microsoft REST API Guidelines](#microsoft-rest-api-guidelines-1)
+  - [1. Abstract](#1-abstract)
+    - [**Guidance for Azure service teams**](#guidance-for-azure-service-teams)
+    - [**Guidance for Microsoft Graph service teams**](#guidance-for-microsoft-graph-service-teams)
+  - [2. Table of contents](#2-table-of-contents)
+  - [3. Introduction](#3-introduction)
     - [3.1. Recommended reading](#31-recommended-reading)
-- [4. Interpreting the guidelines](#4-interpreting-the-guidelines)
+  - [4. Interpreting the guidelines](#4-interpreting-the-guidelines)
     - [4.1. Application of the guidelines](#41-application-of-the-guidelines)
     - [4.2. Guidelines for existing services and versioning of services](#42-guidelines-for-existing-services-and-versioning-of-services)
     - [4.3. Requirements language](#43-requirements-language)
     - [4.4. License](#44-license)
-- [5. Taxonomy](#5-taxonomy)
+  - [5. Taxonomy](#5-taxonomy)
     - [5.1. Errors](#51-errors)
     - [5.2. Faults](#52-faults)
     - [5.3. Latency](#53-latency)
     - [5.4. Time to complete](#54-time-to-complete)
     - [5.5. Long running API faults](#55-long-running-api-faults)
-- [6. Client guidance](#6-client-guidance)
+  - [6. Client guidance](#6-client-guidance)
     - [6.1. Ignore rule](#61-ignore-rule)
     - [6.2. Variable order rule](#62-variable-order-rule)
     - [6.3. Silent fail rule](#63-silent-fail-rule)
-- [7. Consistency fundamentals](#7-consistency-fundamentals)
+  - [7. Consistency fundamentals](#7-consistency-fundamentals)
     - [7.1. URL structure](#71-url-structure)
     - [7.2. URL length](#72-url-length)
     - [7.3. Canonical identifier](#73-canonical-identifier)
     - [7.4. Supported methods](#74-supported-methods)
-        - [7.4.1. POST](#741-post)
-        - [7.4.2. PATCH](#742-patch)
-        - [7.4.3. Creating resources via PATCH (UPSERT semantics)](#743-creating-resources-via-patch-upsert-semantics)
-        - [7.4.4. Options and link headers](#744-options-and-link-headers)
+      - [7.4.1. POST](#741-post)
+      - [7.4.2. PATCH](#742-patch)
+      - [7.4.3. Creating resources via PATCH (UPSERT semantics)](#743-creating-resources-via-patch-upsert-semantics)
+      - [7.4.4. Options and link headers](#744-options-and-link-headers)
     - [7.5. Standard request headers](#75-standard-request-headers)
     - [7.6. Standard response headers](#76-standard-response-headers)
     - [7.7. Custom headers](#77-custom-headers)
     - [7.8. Specifying headers as query parameters](#78-specifying-headers-as-query-parameters)
     - [7.9. PII parameters](#79-pii-parameters)
     - [7.10. Response formats](#710-response-formats)
-        - [7.10.1. Clients-specified response format](#7101-clients-specified-response-format)
-        - [7.10.2. Error condition responses](#7102-error-condition-responses)
+      - [7.10.1. Clients-specified response format](#7101-clients-specified-response-format)
+      - [7.10.2. Error condition responses](#7102-error-condition-responses)
+        - [ErrorResponse : Object](#errorresponse--object)
+        - [Error : Object](#error--object)
+        - [InnerError : Object](#innererror--object)
+        - [Examples](#examples)
     - [7.11. HTTP Status Codes](#711-http-status-codes)
     - [7.12. Client library optional](#712-client-library-optional)
-- [8. CORS](#8-cors)
+  - [8. CORS](#8-cors)
     - [8.1. Client guidance](#81-client-guidance)
-        - [8.1.1. Avoiding preflight](#811-avoiding-preflight)
+      - [8.1.1. Avoiding preflight](#811-avoiding-preflight)
     - [8.2. Service guidance](#82-service-guidance)
-- [9. Collections](#9-collections)
+  - [9. Collections](#9-collections)
     - [9.1. Item keys](#91-item-keys)
     - [9.2. Serialization](#92-serialization)
     - [9.3. Collection URL patterns](#93-collection-url-patterns)
-        - [9.3.1. Nested collections and properties](#931-nested-collections-and-properties)
+      - [9.3.1. Nested collections and properties](#931-nested-collections-and-properties)
     - [9.4. Big collections](#94-big-collections)
     - [9.5. Changing collections](#95-changing-collections)
     - [9.6. Sorting collections](#96-sorting-collections)
-        - [9.6.1. Interpreting a sorting expression](#961-interpreting-a-sorting-expression)
+      - [9.6.1. Interpreting a sorting expression](#961-interpreting-a-sorting-expression)
     - [9.7. Filtering](#97-filtering)
-        - [9.7.1. Filter operations](#971-filter-operations)
-        - [9.7.2. Operator examples](#972-operator-examples)
-        - [9.7.3. Operator precedence](#973-operator-precedence)
+      - [9.7.1. Filter operations](#971-filter-operations)
+      - [9.7.2. Operator examples](#972-operator-examples)
+      - [9.7.3. Operator precedence](#973-operator-precedence)
     - [9.8. Pagination](#98-pagination)
-        - [9.8.1. Server-driven paging](#981-server-driven-paging)
-        - [9.8.2. Client-driven paging](#982-client-driven-paging)
-        - [9.8.3. Additional considerations](#983-additional-considerations)
+      - [9.8.1. Server-driven paging](#981-server-driven-paging)
+      - [9.8.2. Client-driven paging](#982-client-driven-paging)
+      - [9.8.3. Additional considerations](#983-additional-considerations)
     - [9.9. Compound collection operations](#99-compound-collection-operations)
     - [9.10. Empty Results](#910-empty-results)
-- [10. Delta queries](#10-delta-queries)
+  - [10. Delta queries](#10-delta-queries)
     - [10.1. Delta links](#101-delta-links)
     - [10.2. Entity representation](#102-entity-representation)
     - [10.3. Obtaining a delta link](#103-obtaining-a-delta-link)
     - [10.4. Contents of a delta link response](#104-contents-of-a-delta-link-response)
     - [10.5. Using a delta link](#105-using-a-delta-link)
-- [11. JSON standardizations](#11-json-standardizations)
+  - [11. JSON standardizations](#11-json-standardizations)
     - [11.1. JSON formatting standardization for primitive types](#111-json-formatting-standardization-for-primitive-types)
     - [11.2. Guidelines for dates and times](#112-guidelines-for-dates-and-times)
-        - [11.2.1. Producing dates](#1121-producing-dates)
-        - [11.2.2. Consuming dates](#1122-consuming-dates)
-        - [11.2.3. Compatibility](#1123-compatibility)
+      - [11.2.1. Producing dates](#1121-producing-dates)
+      - [11.2.2. Consuming dates](#1122-consuming-dates)
+      - [11.2.3. Compatibility](#1123-compatibility)
     - [11.3. JSON serialization of dates and times](#113-json-serialization-of-dates-and-times)
-        - [11.3.1. The `DateLiteral` format](#1131-the-dateliteral-format)
-        - [11.3.2. Commentary on date formatting](#1132-commentary-on-date-formatting)
+      - [11.3.1. The `DateLiteral` format](#1131-the-dateliteral-format)
+      - [11.3.2. Commentary on date formatting](#1132-commentary-on-date-formatting)
     - [11.4. Durations](#114-durations)
     - [11.5. Intervals](#115-intervals)
     - [11.6. Repeating intervals](#116-repeating-intervals)
-- [12. Versioning](#12-versioning)
+  - [12. Versioning](#12-versioning)
     - [12.1. Versioning formats](#121-versioning-formats)
-        - [12.1.1. Group versioning](#1211-group-versioning)
+      - [12.1.1. Group versioning](#1211-group-versioning)
+        - [Examples of group versioning](#examples-of-group-versioning)
     - [12.2. When to version](#122-when-to-version)
     - [12.3. Definition of a breaking change](#123-definition-of-a-breaking-change)
-- [13. Long running operations](#13-long-running-operations)
+  - [13. Long running operations](#13-long-running-operations)
     - [13.1. Resource based long running operations (RELO)](#131-resource-based-long-running-operations-relo)
     - [13.2. Stepwise long running operations](#132-stepwise-long-running-operations)
-        - [13.2.1. PUT](#1321-put)
-        - [13.2.2. POST](#1322-post)
-        - [13.2.3. POST, hybrid model](#1323-post-hybrid-model)
-        - [13.2.4. Operations resource](#1324-operations-resource)
-        - [13.2.5. Operation resource](#1325-operation-resource)
-        - [13.2.6. Operation tombstones](#1326-operation-tombstones)
-        - [13.2.7. The typical flow, polling](#1327-the-typical-flow-polling)
-        - [13.2.8. The typical flow, push notifications](#1328-the-typical-flow-push-notifications)
-        - [13.2.9. Retry-After](#1329-retry-after)
+      - [13.2.1. PUT](#1321-put)
+      - [13.2.2. POST](#1322-post)
+      - [13.2.3. POST, hybrid model](#1323-post-hybrid-model)
+      - [13.2.4. Operations resource](#1324-operations-resource)
+      - [13.2.5. Operation resource](#1325-operation-resource)
+        - [Percent complete](#percent-complete)
+        - [Target resource location](#target-resource-location)
+      - [13.2.6. Operation tombstones](#1326-operation-tombstones)
+      - [13.2.7. The typical flow, polling](#1327-the-typical-flow-polling)
+        - [Example of the typical flow, polling](#example-of-the-typical-flow-polling)
+      - [13.2.8. The typical flow, push notifications](#1328-the-typical-flow-push-notifications)
+        - [Example of the typical flow, push notifications existing subscription](#example-of-the-typical-flow-push-notifications-existing-subscription)
+      - [13.2.9. Retry-After](#1329-retry-after)
     - [13.3. Retention policy for operation results](#133-retention-policy-for-operation-results)
-- [14. Throttling, Quotas, and Limits](#14-throttling-quotas-and-limits)
+  - [14. Throttling, Quotas, and Limits](#14-throttling-quotas-and-limits)
     - [14.1. Principles](#141-principles)
     - [14.2. Return Codes (429 vs 503)](#142-return-codes-429-vs-503)
     - [14.3. Retry-After and RateLimit Headers](#143-retry-after-and-ratelimit-headers)
     - [14.4. Service Guidance](#144-service-guidance)
-        - [14.4.1. Responsiveness](#1441-responsiveness)
-        - [14.4.2. Rate Limits and Quotas](#1442-rate-limits-and-quotas)
-        - [14.4.3. Overloaded services](#1443-overloaded-services)
-        - [14.4.4. Example Response](#1444-example-response)
+      - [14.4.1. Responsiveness](#1441-responsiveness)
+      - [14.4.2. Rate Limits and Quotas](#1442-rate-limits-and-quotas)
+      - [14.4.3. Overloaded services](#1443-overloaded-services)
+      - [14.4.4. Example Response](#1444-example-response)
     - [14.5. Caller Guidance](#145-caller-guidance)
     - [14.6. Handling callers that ignore Retry-After headers](#146-handling-callers-that-ignore-retry-after-headers)
-- [15. Push notifications via webhooks](#15-push-notifications-via-webhooks)
+  - [15. Push notifications via webhooks](#15-push-notifications-via-webhooks)
     - [15.1. Scope](#151-scope)
     - [15.2. Principles](#152-principles)
     - [15.3. Types of subscriptions](#153-types-of-subscriptions)
     - [15.4. Call sequences](#154-call-sequences)
     - [15.5. Verifying subscriptions](#155-verifying-subscriptions)
     - [15.6. Receiving notifications](#156-receiving-notifications)
-        - [15.6.1. Notification payload](#1561-notification-payload)
+      - [15.6.1. Notification payload](#1561-notification-payload)
     - [15.7. Managing subscriptions programmatically](#157-managing-subscriptions-programmatically)
-        - [15.7.1. Creating subscriptions](#1571-creating-subscriptions)
-        - [15.7.2. Updating subscriptions](#1572-updating-subscriptions)
-        - [15.7.3. Deleting subscriptions](#1573-deleting-subscriptions)
-        - [15.7.4. Enumerating subscriptions](#1574-enumerating-subscriptions)
+      - [15.7.1. Creating subscriptions](#1571-creating-subscriptions)
+      - [15.7.2. Updating subscriptions](#1572-updating-subscriptions)
+      - [15.7.3. Deleting subscriptions](#1573-deleting-subscriptions)
+      - [15.7.4. Enumerating subscriptions](#1574-enumerating-subscriptions)
     - [15.8. Security](#158-security)
-- [16. Unsupported requests](#16-unsupported-requests)
+  - [16. Unsupported requests](#16-unsupported-requests)
     - [16.1. Essential guidance](#161-essential-guidance)
     - [16.2. Feature allow list](#162-feature-allow-list)
-        - [16.2.1. Error response](#1621-error-response)
-- [17. Naming guidelines](#17-naming-guidelines)
+      - [16.2.1. Error response](#1621-error-response)
+  - [17. Naming guidelines](#17-naming-guidelines)
     - [17.1. Approach](#171-approach)
     - [17.2. Casing](#172-casing)
     - [17.3. Names to avoid](#173-names-to-avoid)
@@ -160,10 +180,10 @@ This document establishes the guidelines Microsoft REST APIs SHOULD follow so RE
     - [17.7. Name properties](#177-name-properties)
     - [17.8. Collections and counts](#178-collections-and-counts)
     - [17.9. Common property names](#179-common-property-names)
-- [18. Appendix](#18-appendix)
+  - [18. Appendix](#18-appendix)
     - [18.1. Sequence diagram notes](#181-sequence-diagram-notes)
-        - [18.1.1. Push notifications, per user flow](#1811-push-notifications-per-user-flow)
-        - [18.1.2. Push notifications, firehose flow](#1812-push-notifications-firehose-flow)
+      - [18.1.1. Push notifications, per user flow](#1811-push-notifications-per-user-flow)
+      - [18.1.2. Push notifications, firehose flow](#1812-push-notifications-firehose-flow)
 
 <!-- /TOC -->
 
diff --git a/README.md b/README.md
@@ -6,10 +6,10 @@ 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. 
+### Guidance for Azure service teams
+Azure service teams should use 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. 
 
-### Additional guidance for Microsoft Graph service teams
+### Guidance for Microsoft Graph service teams
 Graph service teams should reference the companion document, [Graph REST API Guidelines](./graph/GuidelinesGraph.md) when building or modifying their services. This document and the associated pattern catalog provides a refined set of guidance targeted specifically for Microsoft Graph services.
 
 [![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/)
