Skip to content

Commit d9b7bce

Browse files
darrelmillerdarrelmiller
authored
Merge pull request #327 from microsoft/graph
publish Microsoft Graph specific guidelines and patterns
2 parents 4237290 + 7a038b6 commit d9b7bce

9 files changed

+1044
-16
lines changed

‎graph/GuidelinesGraph.md

Lines changed: 434 additions & 0 deletions
Large diffs are not rendered by default.

‎graph/ModelExample.png

48.8 KB
Loading

‎graph/SummaryOfGraphDeltas.md

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# Graph API Design API Patterns
2+
3+
## Introduction
4+
5+
The Graph REST API guidelines are an extension of the [Microsoft REST API guidelines](../guidelines). Readers of this document are assumed to be also reading the [Microsoft REST API guidelines](../guidelines) and be familiar with them. Graph guidance is a superset of the Microsoft API guidelines and services should follow them *except* where this document outlines specific differences or exceptions to those guidelines. This document does contain additional Graph-specific guidance and additional details.
6+
7+
The following table of contents links back to the primary guidelines where there are no differences in Graph guidelines. Where differences exist, the section heading is **bold**.
8+
9+
## 2. Table of contents
10+
<!-- TOC depthFrom:2 depthTo:4 orderedList:false updateOnSave:false withLinks:true -->
11+
12+
- [Microsoft REST API Guidelines Working Group](../Guidelines.md#microsoft-rest-api-guidelines-working-group)
13+
- [1. Abstract](../Guidelines.md#1-abstract)
14+
- [2. Table of contents](../Guidelines.md#2-table-of-contents)
15+
- [3. Introduction](../Guidelines.md#3-introduction)
16+
- [3.1. Recommended reading](../Guidelines.md#31-recommended-reading)
17+
- [4. Interpreting the guidelines](../Guidelines.md#4-interpreting-the-guidelines)
18+
- [4.1. Application of the guidelines](../Guidelines.md#41-application-of-the-guidelines)
19+
- [4.2. Guidelines for existing services and versioning of services](../Guidelines.md#42-guidelines-for-existing-services-and-versioning-of-services)
20+
- [4.3. Requirements language](../Guidelines.md#43-requirements-language)
21+
- [4.4. License](../Guidelines.md#44-license)
22+
- [5. Taxonomy](../Guidelines.md#5-taxonomy)
23+
- [5.1. Errors](../Guidelines.md#51-errors)
24+
- [5.2. Faults](../Guidelines.md#52-faults)
25+
- [5.3. Latency](../Guidelines.md#53-latency)
26+
- [5.4. Time to complete](../Guidelines.md#54-time-to-complete)
27+
- [5.5. Long running API faults](../Guidelines.md#55-long-running-api-faults)
28+
- [6. Client guidance](../Guidelines.md#6-client-guidance)
29+
- [6.1. Ignore rule](../Guidelines.md#61-ignore-rule)
30+
- [6.2. Variable order rule](../Guidelines.md#62-variable-order-rule)
31+
- [6.3. Silent fail rule](../Guidelines.md#63-silent-fail-rule)
32+
- [7. Consistency fundamentals](../Guidelines.md#7-consistency-fundamentals)
33+
- [7.1. URL structure](../Guidelines.md#71-url-structure)
34+
- [7.2. URL length](../Guidelines.md#72-url-length)
35+
- [7.3. Canonical identifier](../Guidelines.md#73-canonical-identifier)
36+
- [7.4. Supported methods](../Guidelines.md#74-supported-methods)
37+
- [7.4.1. POST](../Guidelines.md#741-post)
38+
- [7.4.2. PATCH](../Guidelines.md#742-patch)
39+
- [7.4.3. Creating resources via PATCH (UPSERT semantics)](../Guidelines.md#743-creating-resources-via-patch-upsert-semantics)
40+
- [7.4.4. Options and link headers](../Guidelines.md#744-options-and-link-headers)
41+
- [7.5. Standard request headers](../Guidelines.md#75-standard-request-headers)
42+
- [7.6. Standard response headers](../Guidelines.md#76-standard-response-headers)
43+
- [7.7. Custom headers](../Guidelines.md#77-custom-headers)
44+
- [7.8. Specifying headers as query parameters](../Guidelines.md#78-specifying-headers-as-query-parameters)
45+
- [7.9. PII parameters](../Guidelines.md#79-pii-parameters)
46+
- [7.10. Response formats](../Guidelines.md#710-response-formats)
47+
- [7.10.1. Clients-specified response format](../Guidelines.md#7101-clients-specified-response-format)
48+
- [7.10.2. Error condition responses](../Guidelines.md#7102-error-condition-responses)
49+
- [7.11. HTTP Status Codes](../Guidelines.md#711-http-status-codes)
50+
- [7.12. Client library optional](../Guidelines.md#712-client-library-optional)
51+
- [8. CORS](../Guidelines.md#8-cors)
52+
- [8.1. Client guidance](../Guidelines.md#81-client-guidance)
53+
- [8.1.1. Avoiding preflight](../Guidelines.md#811-avoiding-preflight)
54+
- [8.2. Service guidance](../Guidelines.md#82-service-guidance)
55+
- [9. Collections](../Guidelines.md#9-collections)
56+
- [9.1. Item keys](../Guidelines.md#91-item-keys)
57+
- [9.2. Serialization](../Guidelines.md#92-serialization)
58+
- [9.3. Collection URL patterns](../Guidelines.md#93-collection-url-patterns)
59+
- [9.3.1. Nested collections and properties](../Guidelines.md#931-nested-collections-and-properties)
60+
- [9.4. Big collections](../Guidelines.md#94-big-collections)
61+
- [9.5. Changing collections](../Guidelines.md#95-changing-collections)
62+
- [9.6. Sorting collections](../Guidelines.md#96-sorting-collections)
63+
- [9.6.1. Interpreting a sorting expression](../Guidelines.md#961-interpreting-a-sorting-expression)
64+
- [9.7. Filtering](../Guidelines.md#97-filtering)
65+
- [9.7.1. Filter operations](../Guidelines.md#971-filter-operations)
66+
- [9.7.2. Operator examples](../Guidelines.md#972-operator-examples)
67+
- [9.7.3. Operator precedence](../Guidelines.md#973-operator-precedence)
68+
- [9.8. Pagination](../Guidelines.md#98-pagination)
69+
- [9.8.1. Server-driven paging](../Guidelines.md#981-server-driven-paging)
70+
- [9.8.2. Client-driven paging](../Guidelines.md#982-client-driven-paging)
71+
- [9.8.3. Additional considerations](../Guidelines.md#983-additional-considerations)
72+
- [9.9. Compound collection operations](../Guidelines.md#99-compound-collection-operations)
73+
- [**9a. Resource Design**](#9a-resource-design)
74+
- [**9a.1. Noun Resources**](#9a1-noun-resources)
75+
- [**9a.2. Verb Resources**](#9a2-verb-resources)
76+
- [**9a.3. Resource Modeling**](#9a3-resource-modeling)
77+
- [10. Delta queries](#10-delta-queries)
78+
- [10.1. Delta links](../Guidelines.md#101-delta-links)
79+
- [10.2. Entity representation](../Guidelines.md#102-entity-representation)
80+
- [10.3. Obtaining a delta link](../Guidelines.md#103-obtaining-a-delta-link)
81+
- [10.4. Contents of a delta link response](../Guidelines.md#104-contents-of-a-delta-link-response)
82+
- [10.5. Using a delta link](../Guidelines.md#105-using-a-delta-link)
83+
- [11. JSON standardizations](../Guidelines.md#11-json-standardizations)
84+
- [11.1. JSON formatting standardization for primitive types](../Guidelines.md#111-json-formatting-standardization-for-primitive-types)
85+
- [11.2. Guidelines for dates and times](../Guidelines.md#112-guidelines-for-dates-and-times)
86+
- [11.2.1. Producing dates](../Guidelines.md#1121-producing-dates)
87+
- [11.2.2. Consuming dates](../Guidelines.md#1122-consuming-dates)
88+
- [11.2.3. Compatibility](../Guidelines.md#1123-compatibility)
89+
- [11.3. JSON serialization of dates and times](../Guidelines.md#113-json-serialization-of-dates-and-times)
90+
- [11.3.1. The `DateLiteral` format](../Guidelines.md#1131-the-dateliteral-format)
91+
- [11.3.2. Commentary on date formatting](../Guidelines.md#1132-commentary-on-date-formatting)
92+
- [11.4. Durations](../Guidelines.md#114-durations)
93+
- [11.5. Intervals](../Guidelines.md#115-intervals)
94+
- [11.6. Repeating intervals](../Guidelines.md#116-repeating-intervals)
95+
- [**11.7. Evolvable Enums**](#117-evolvable-enums)
96+
- [**11.8. Dictionary Types**](#118-dictionary-types)
97+
- [**11.9. Ommitted Properties**](#119-ommitted-properties)
98+
- [12. Versioning](../Guidelines.md#12-versioning)
99+
- [12.1. Versioning formats](../Guidelines.md#121-versioning-formats)
100+
- [12.1.1. Group versioning](../Guidelines.md#1211-group-versioning)
101+
- [12.2. When to version](../Guidelines.md#122-when-to-version)
102+
- [12.3. Definition of a breaking change](../Guidelines.md#123-definition-of-a-breaking-change)
103+
- [**13. Long running operations**](#13-long-running-operations)
104+
- [**13.1. Resource based long running operations (RELO)**](../long-running-operations.md#131-resource-based-long-running-operations-relo)
105+
- [**13.2. Stepwise long running operations**](../long-running-operations.md#132-stepwise-long-running-operations)
106+
- [13.2.1. PUT](../Guidelines.md#1321-put)
107+
- [13.2.2. POST](../Guidelines.md#1322-post)
108+
- [13.2.3. POST, hybrid model](../Guidelines.md#1323-post-hybrid-model)
109+
- [13.2.4. Operations resource](../Guidelines.md#1324-operations-resource)
110+
- [13.2.5. Operation resource](../Guidelines.md#1325-operation-resource)
111+
- [13.2.6. Operation tombstones](../Guidelines.md#1326-operation-tombstones)
112+
- [13.2.7. The typical flow, polling](../Guidelines.md#1327-the-typical-flow-polling)
113+
- [13.2.8. The typical flow, push notifications](../Guidelines.md#1328-the-typical-flow-push-notifications)
114+
- [13.2.9. Retry-After](../Guidelines.md#1329-retry-after)
115+
- [13.3. Retention policy for operation results](../Guidelines.md#133-retention-policy-for-operation-results)
116+
- [14. Throttling, Quotas, and Limits](../Guidelines.md#14-throttling-quotas-and-limits)
117+
- [14.1. Principles](../Guidelines.md#141-principles)
118+
- [14.2. Return Codes (429 vs 503)](../Guidelines.md#142-return-codes-429-vs-503)
119+
- [14.3. Retry-After and RateLimit Headers](../Guidelines.md#143-retry-after-and-ratelimit-headers)
120+
- [14.4. Service Guidance](../Guidelines.md#144-service-guidance)
121+
- [14.4.1. Responsiveness](../Guidelines.md#1441-responsiveness)
122+
- [14.4.2. Rate Limits and Quotas](../Guidelines.md#1442-rate-limits-and-quotas)
123+
- [14.4.3. Overloaded services](../Guidelines.md#1443-overloaded-services)
124+
- [14.4.4. Example Response](../Guidelines.md#1444-example-response)
125+
- [14.5. Caller Guidance](../Guidelines.md#145-caller-guidance)
126+
- [14.6. Handling callers that ignore Retry-After headers](../Guidelines.md#146-handling-callers-that-ignore-retry-after-headers)
127+
- [**15. Push notifications via webhooks**](#15-push-notifications-via-webhooks)
128+
- [15.1. Scope](../Guidelines.md#151-scope)
129+
- [15.2. Principles](../Guidelines.md#152-principles)
130+
- [15.3. Types of subscriptions](../Guidelines.md#153-types-of-subscriptions)
131+
- [15.4. Call sequences](../Guidelines.md#154-call-sequences)
132+
- [15.5. Verifying subscriptions](../Guidelines.md#155-verifying-subscriptions)
133+
- [15.6. Receiving notifications](../Guidelines.md#156-receiving-notifications)
134+
- [15.6.1. Notification payload](../Guidelines.md#1561-notification-payload)
135+
- [15.7. Managing subscriptions programmatically](../Guidelines.md#157-managing-subscriptions-programmatically)
136+
- [15.7.1. Creating subscriptions](../Guidelines.md#1571-creating-subscriptions)
137+
- [15.7.2. Updating subscriptions](../Guidelines.md#1572-updating-subscriptions)
138+
- [15.7.3. Deleting subscriptions](../Guidelines.md#1573-deleting-subscriptions)
139+
- [15.7.4. Enumerating subscriptions](../Guidelines.md#1574-enumerating-subscriptions)
140+
- [15.8. Security](../Guidelines.md#158-security)
141+
- [16. Unsupported requests](../Guidelines.md#16-unsupported-requests)
142+
- [16.1. Essential guidance](../Guidelines.md#161-essential-guidance)
143+
- [16.2. Feature allow list](../Guidelines.md#162-feature-allow-list)
144+
- [16.2.1. Error response](../Guidelines.md#1621-error-response)
145+
- [17. Naming guidelines](../Guidelines.md#17-naming-guidelines)
146+
- [17.1. Approach](../Guidelines.md#171-approach)
147+
- [17.2. Casing](../Guidelines.md#172-casing)
148+
- [17.3. Names to avoid](../Guidelines.md#173-names-to-avoid)
149+
- [17.4. Forming compound names](../Guidelines.md#174-forming-compound-names)
150+
- [17.5. Identity properties](../Guidelines.md#175-identity-properties)
151+
- [17.6. Date and time properties](../Guidelines.md#176-date-and-time-properties)
152+
- [17.7. Name properties](../Guidelines.md#177-name-properties)
153+
- [17.8. Collections and counts](../Guidelines.md#178-collections-and-counts)
154+
- [17.9. Common property names](../Guidelines.md#179-common-property-names)
155+
- [**17.10. Type namespaces**](#1710-type-namespaces)
156+
- [18. Appendix](../Guidelines.md#18-appendix)
157+
- [18.1. Sequence diagram notes](../Guidelines.md#181-sequence-diagram-notes)
158+
- [18.1.1. Push notifications, per user flow](../Guidelines.md#1811-push-notifications-per-user-flow)
159+
- [18.1.2. Push notifications, firehose flow](../Guidelines.md#1812-push-notifications-firehose-flow)
160+
- [**18.2. Additional resources**](#182-additional-resources)
161+
162+
<!-- /TOC -->
163+
164+
## Summaries of the deltas in the Microsoft Graph Design Guidelines
165+
166+
### 9a. Resource Design
167+
168+
#### 9a.1. Noun Resources
169+
170+
While HTTP defines no constraints on how different resources are related together, it does encourage the use of URL path segment hierarchies to convey a relationship. In addition to the hierarchy of resources, there are also lifetime relationships between resources, the notions of [singletons, entitySets, entities, complex types and navigation properties](entity-complex) make it possible to define a set of lifetime relationships between resources.
171+
172+
#### 9a.2. Verb Resources
173+
174+
Noun-based resources are not always the best fit for meeting the requirements of a client. There are read-only and write scenarios where a resource can be used to represent some kind of data processing operation. The terms [function and action](Functions-and-actions) are used to identify read and write operation style resources, respectively.
175+
176+
#### 9a.3. Resource Modeling
177+
178+
There are a number of principles to be aware of when modeling resources for Microsoft Graph. [Modeling variants](modeling-variants) is important when resources have have a subset of common properties and behavior.
179+
180+
### 10. Deltas
181+
182+
The ability to track changes (pull) occuring in the data exposed by Microsoft Graph. This is addressed implementing [change tracking (aka delta query)](deltas).
183+
184+
### 11.7. Evolvable Enums
185+
186+
[Evolvable enums](evolvable-enums) enable the use of enumerations that can add new values over time without breaking clients applications.
187+
188+
### 11.8. Dictionary Types
189+
190+
For scenarios where there is a need to persist a variable number of properties, a [dictionary type](./dictionary/index.md) may be useful.
191+
192+
### 11.9. Omitting Properties
193+
194+
For scenarios where the server contains business logic that determines if a property value should be returned, or not, to the client, a returned representation can be annotated to indicate where properties are [omitted](ommitting-properties).
195+
196+
### 13. Long running operations
197+
198+
Long running operations are mostly unchanged. The most significant difference is that instead of using `Operation-Location` as the header to point to the Operation, the use of the standard `Location` header is recommended. In hybrid scenarios, a `Content-Location` header can be used to indicate the URL of the created resource and the 202 response can contain a payload. Details of the diffences are described in detail in the [Long Running Operations](long-running-operations) document.
199+
200+
### 15. Push notifications via webHooks
201+
202+
To determine how the Graph docs differ than the Microsoft REST API Guidelines.
203+
The ability to get notified (push) when a change occurs in the data exposed by Microsoft Graph. This is addressed implementing [change notifications (aka webhooks)](webhooks).
204+
205+
### 17.10. Type Namespaces
206+
207+
Microsoft Graph model types can be declared within a [type namespaces](type-namespaces) to reduce the need to prefix types with a qualifier to ensure uniqueness.
208+
209+
### 18.2. Additional resources
210+
211+
The links below provide a set of rules to think through as you design your API.
212+
213+
- [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines/)
214+
- [OData Guidelines](http://www.odata.org/documentation/)
215+
- [Microsoft Graph Documentation](https://developer.microsoft.com/en-us/graph/docs/concepts/overview)
216+
- [Microsoft Graph Explorer](https://aka.ms/ge)

‎graph/deprecation.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
### Deprecation Guidelines
2+
3+
If your API requires the introduction of breaking changes you must add Revisions annotations to the API definition with the following terms:
4+
5+
6+
- Date: Date when the element was marked as deprecated.
7+
- Version: Used to organize the ChangeLog. Use the format "YYYY-MM/Category" where "YYYY-MM" is the month the deprecation is announced, and "Category" is the category under which the change is described.
8+
- Kind: Deprecated -
9+
- Description: Human readable description of the change: Used in changelog, documentation etc.
10+
- RemovalDate: Earliest date when the element may be removed.
11+
12+
The annotation can be applied to a type, an entity set, a singleton,a property, a
13+
navigation property, a function or an action. If a type is marked as deprecated, it
14+
is not necessary to mark the members of that type as deprecated, nor is it necessary
15+
to annotate any usages of that type.
16+
17+
**Example of property annotation:**
18+
19+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
20+
<EntityType Name="outlookTask" BaseType="Microsoft.OutlookServices.outlookItem" ags:IsMaster="true" ags:WorkloadName="Task" ags:EnabledForPassthrough="true">
21+
<Annotation Term="Org.OData.Core.V1.Revisions">
22+
<Collection>
23+
<Record>
24+
<PropertyValue Property = "Date" Date="2022-03-30"/>
25+
<PropertyValue Property = "Version" String="2022-03/Tasks_And_Plans"/>
26+
<PropertyValue Property = "Kind" EnumMember="Org.OData.Core.V1.RevisionKind/Deprecated"/>
27+
<PropertyValue Property = "Description" String="The Outlook tasks API is deprecated and will stop returning data on June 30, 2024. Please use the new To Do API."/>
28+
<PropertyValue Property = "RemovalDate" Date="2024-06-30"/>
29+
</Record>
30+
</Collection>
31+
</Annotation>
32+
...
33+
</EntityType>
34+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
35+
36+
When the request URL contains a reference to a deprecated model element, the gateway will add a [Deprecation
37+
header](https://tools.ietf.org/html/draft-dalal-deprecation-header-02) (with the
38+
date the element was marked as deprecated) and a Sunset header (with the date of 2
39+
years beyond the Deprecation date) to the response.
40+
41+
**Deprecation header example:**
42+
43+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
44+
Deprecation: Wed, 30 Mar 2022 11:59:59 GMT
45+
Sunset: Thursday, 30 June 2024 23:59:59 GMT
46+
Link: https://docs.microsoft.com/en-us/graph/changelog#2022-03-30_name ; rel="deprecation"; type="text/html"; title="name",https://docs.microsoft.com/en-us/graph/changelog#2022-03-30_state ; rel="deprecation"; type="text/html"; title="state"
47+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

‎graph/patterns/PatternDescriptionTemplate.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Pattern Name
2+
3+
Microsoft Graph API Design Pattern
4+
5+
 
6+
7+
### *Provide a short description of the pattern.*
8+
9+
<BR>
10+
11+
## Problem
12+
--------
13+
*Describe business context relevant for the pattern.*
14+
*Provide a short description of the problem.*
15+
16+
* *
17+
18+
## Solution
19+
--------
20+
21+
*Describe how to implement the solution to solve the problem.*
22+
*Describe related patterns.*
23+
24+
* *
25+
26+
## When to Use this Pattern
27+
------------------------
28+
29+
*Describe when and why the solution is applicable and when it may not.*
30+
31+
* *
32+
33+
## Issues and Considerations
34+
-------------------------
35+
36+
*Describe tradeoffs of the solution.*
37+
38+
39+
* *
40+
41+
## Example
42+
-------
43+
44+
*Provide a short example from real life*
45+
46+
* * 
47+
48+
49+
50+

‎graph/dictionary/client-guidance.md renamed to ‎graph/patterns/dictionary-client-guidance.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Dictionary types
22

3+
Note: this document is to be moved into a central client guidance document in the future.
4+
35
The client guidance is a collection of additional information provided to SDK implementers and client applications. This information is meant to help understand how various guidelines and concept translate in their world and clarify a few unknowns. You should always read the corresponding guideline first to get a context understanding.
46

57
[Read the guideline](./index.md).

0 commit comments

Comments
 (0)