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: graph/GuidelinesGraph.md
+52-53Lines changed: 52 additions & 53 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,100 +31,99 @@ Table of contents
31
31
32
32
## Introduction
33
33
34
-
When building a digital ecosystem API usability becomes a business priority. Success of your ecosystem depends on APIs that are easy to discover, simple to use, fit for purpose, and consistent across your products.
34
+
When building a digital ecosystem API, usability becomes a business priority. The success of your ecosystem depends on APIs that are easy to discover, simple to use, fit for purpose, and consistent across your products.
35
35
36
36
This document offers guidance that Microsoft Graph API producer teams MUST follow to
37
-
ensure that Microsoft Graph has a consistent and easy to use API surface. A new API design should meet the
38
-
following goals:
37
+
ensure that Microsoft Graph has a consistent and easy-to-use API surface. A new API design should meet the following goals:
39
38
40
-
\- Developer friendly via consistent naming, patterns, and web standards (HTTP,
41
-
REST, JSON)
39
+
- Be developer friendly by using consistent naming, patterns, and web standards (HTTP, REST, JSON).
42
40
43
-
\- Work well with SDKs in many programming languages.
41
+
- Work well with SDKs in many programming languages.
44
42
45
-
\- Sustainable & evolvable via clear API contracts.
43
+
- Be sustainable and evolvable by using clear API contracts.
46
44
47
-
The Microsoft Graph guidelines are an extension of the Microsoft REST API
48
-
guidelines. Readers are assumed also be reading and following the Microsoft REST API
49
-
guidelines except where this document outlines specific differences or exceptions to those guidelines.
50
-
Together these guidelines and a library of API patterns serve as the means by
51
-
which API teams discuss and come to consensus on API review requirements.
45
+
The Microsoft Graph REST API Guidelines are an extension of the
46
+
[Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines/). It is assumed that readers are following the Microsoft REST API Guidelines except where this document outlines specific differences or exceptions to those guidelines. Together, these guidelines and a library of API patterns serve as the means by which API teams discuss and come to consensus on API review requirements.
52
47
53
48
Technology and software are constantly changing and evolving, and as such, this
54
-
is intended to be a living document. API guidelines that change frequently lead to an uneven and inconsistent API surface. Consequently, this document will more frequently change to add guidance in areas previously uncovered, or to clarify existing guidance. It will less frequently change the directional guidance it has already provided.
55
-
To suggest a change or propose a new idea, [open an issue](https://github.com/microsoft/api-guidelines/issues/new/choose).
49
+
is intended to be a living document. API guidelines that change frequently lead to an uneven and inconsistent API surface. Consequently, this document will frequently change to add guidance in areas previously uncovered or to clarify existing guidance. It will less frequently change the directional guidance it has already provided. To suggest a change or propose a new idea,
50
+
[open an issue](https://github.com/microsoft/api-guidelines/issues/new/choose).
56
51
57
52
### Legend
58
53
59
54
This document offers prescriptive guidance labeled as follows:
60
55
61
-
:heavy_check_mark:**MUST** satisfy this specification.
56
+
:heavy_check_mark:**MUST** satisfy this specification.
62
57
63
-
:no_entry:**MUST NOT** use this pattern.
58
+
:no_entry:**MUST NOT** use this pattern.
64
59
65
-
:ballot_box_with_check:**SHOULD** fulfill this specification.
60
+
:ballot_box_with_check:**SHOULD** fulfill this specification.
66
61
67
-
:warning:**SHOULD NOT** adopt this pattern.
62
+
:warning:**SHOULD NOT** adopt this pattern.
68
63
69
-
If not following this advice, you MUST disclose your reasons during the Microsoft Graph API review.
64
+
If you do not follow this advice, you MUST disclose your reasons during the Microsoft Graph API review.
70
65
71
66
## Design approach
72
67
73
-
The design of your API is arguably the most important investment you will make. API design is what creates the first impression for developers when they discover and learn how to use your APIs. We promote API-first design approach where you begin your product design by focusing on how information will be exchanged and represented and creating an interface contract for your API which is followed by design and implementation of the backing service. This approach ensures decoupling of the interface from your implementation and is essential for agility, predictability, and reuse of your APIs. Established interface contract allows developers to use your API while internal teams are still working on implementation; API specifications enable designing of user experience and test cases in parallel. Starting with user-facing contracts also promotes a good understanding of system interactions, your modeling domain, and understanding of how the service will evolve.
68
+
The design of your API is arguably the most important investment you will make. API design is what creates the first impression for developers when they discover and learn how to use your APIs. We promote an API-first design approach where you begin your product design by focusing on how information is exchanged and represented and by creating an interface contract for your API, which is followed by design and implementation of the backing service. This approach ensures decoupling of the interface from your implementation and is essential for agility, predictability, and reuse of your APIs.
74
69
75
-
Microsoft Graph supports resource and query-based API styles that follow HTTP, REST, and JSON standards, where API contract is described using OData conventions and schema definition. For more information, see [Documentation · OData Version 4.01](https://www.odata.org/documentation/).
70
+
An established interface contract allows developers to use your API while internal teams are still working on implementation; API specifications enable designing user experience and test cases in parallel. Starting with user-facing contracts also promotes a good understanding of system interactions, your modeling domain, and an understanding of how the service will evolve.
76
71
77
-
In general API design includes the following steps:
72
+
Microsoft Graph supports resource and query-based API styles that follow HTTP, REST, and JSON standards, where the API contract is described by using OData conventions and schema definition. For more information, see [Documentation · OData Version 4.01](https://www.odata.org/documentation/).
78
73
79
-
- Outline the key current and future scenarios for API consumers
74
+
In general, API design includes the following steps:
75
+
76
+
1. Outline the key current and future scenarios for API consumers.
80
77
81
-
- Define your domain model
78
+
1. Define your domain model.
82
79
83
-
- Derive and name your API resources
80
+
1. Derive and name your API resources.
84
81
85
-
- Describe relationships between resources
82
+
1. Describe relationships between resources.
86
83
87
-
- Determine required behavior
84
+
1. Determine required behavior.
88
85
89
-
- Determine user roles and application permissions
86
+
1. Determine user roles and application permissions.
90
87
91
-
- Specify errors
88
+
1. Specify errors.
92
89
93
-
When creating your API contract you will define resources based on the domain model supporting your service and identify interactions based on user scenarios. Good API design goes beyond modeling the current state of resources and it is important to plan ahead how API evolves. For this it is essential to understand and document your user scenarios as the foundation of the API design. There is no one-to-one correspondence between domain model elements and API resources because you should simplify your customer facing APIs for better usability and to obfuscate implementation details. We recommend creating a simple resource diagram, like the following, to show resources and their relationships and make it easier to reason about modeling choices and the shape of your API.
94
-
90
+
When creating your API contract, you define resources based on the domain model supporting your service and identify interactions based on user scenarios. Good API design goes beyond modeling the current state of resources. It is important to plan ahead how the API evolves; to do this, it is essential to understand and document your user scenarios as the foundation of the API design. There is no one-to-one correspondence between domain model elements and API resources because you should simplify your customer facing APIs for better usability and to obfuscate implementation details.
95
91
96
-
After resources are defined it’s time to think about the behavior of your API which can be expressed via HTTP methods and operational resources such as functions and actions. As you think about API behavior you identify a happy path and various exceptions and deviations which will be expressed as errors and represented using HTTP codes and error messages.
92
+
We recommend creating a simple resource diagram like the following to show resources and their relationships and make it easier to reason about modeling choices and the shape of your API.
93
+
94
+
97
95
98
-
At every step of your design you need to consider security, privacy and compliance as intrinsic components of your API implementation.
96
+
After you define your resources, it’s time to think about the behavior of your API, which can be expressed via HTTP methods and operational resources such as functions and actions. As you think about API behavior, you identify a happy path and various exceptions and deviations that will be expressed as errors and represented by using HTTP codes and error messages.
99
97
98
+
At every step of your design, you need to consider security, privacy, and compliance as intrinsic components of your API implementation.
100
99
101
100
### Naming
102
101
103
-
API resources are typically described by nouns. Resource and property names appear in API URLs and payloads and must be descriptive and easy to understand for developers. Ease of understanding comes from familiarity and recognitiontherefore when thinking about naming you should favor consistency with other Microsoft Graph APIs, names in the product user interface, and industry standards. Microsoft Graph naming conventions follow [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines/).
102
+
API resources are typically described by nouns. Resource and property names appear in API URLs and payloads and must be descriptive and easy to understand. Ease of understanding comes from familiarity and recognition; therefore, when thinking about naming, you should favor consistency with other Microsoft Graph APIs, names in the product user interface, and industry standards. Microsoft Graph naming conventions follow the[Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines/).
104
103
105
104
Following is a short summary of the most often used conventions.
|:no_entry:**MUST NOT** use redundant words in names. | - **Right:** /places/{id}/**displayName**and /phones/{id}/**number** <BR> - **Wrong** /places/{id}/*placeName* and /phones/{id}/**phoneNumber**|
110
-
|:warning:**SHOULD NOT** use brand names in type or property names. | - **Right:** chat <BR> - **Wrong** teamsChat |
111
-
|:warning:**SHOULD NOT** use acronyms or abbreviations unless they are broadly understood. | - **Right:** url or htmlSignature <BR> - **Wrong** msodsUrl or dlp |
112
-
|:heavy_check_mark:**MUST** use singular nouns for type names. | - **Right:** address <BR> - **Wrong** addresses |
113
-
|:heavy_check_mark:**MUST** use plural nouns for collections (for listing a type or collection properties). | - **Right:** addresses <BR> - **Wrong** address |
114
-
|:ballot_box_with_check:**SHOULD** pluralize the noun even when followed by an adjective (a "postpositive").| - **Right:** passersby or mothersInLaw <BR> - **Wrong** notaryPublics or motherInLaws |
115
-
|**casing**||
116
-
|:heavy_check_mark:**MUST** use lower camel case for *all* names and namespaces | - **Right:** automaticRepliesStatus. <BR> - **Wrong** kebab-case or snake_case.|
117
-
|:ballot_box_with_check:**SHOULD** case two-letter acronyms with the same case. | - **Right:** ioLimit or totalIOAmount <BR> - **Wrong** iOLimit or totalIoAmount |
118
-
|:ballot_box_with_check:**SHOULD** case three+ letter acronyms the same as a normal word. | - **Right:** fidoKey or oauthUrl <BR> - **Wrong** webHTML |
119
-
|:no_entry:**MUST NOT** capitalize the word following a [prefix](https://www.thoughtco.com/common-prefixes-in-english-1692724) or words within a [compound word](http://www.learningdifferences.com/Main%20Page/Topics/Compound%20Word%20Lists/Compound_Word_%20Lists_complete.htm). | - **Right:** subcategory, geocoordinate or crosswalk <BR> - **Wrong** metaData, semiCircle or airPlane |
120
-
|:heavy_check_mark:**MUST** capitalize within hyphenated and open (spaced) compound words. | - **Right:** fiveYearOld, daughterInLaw or postOffice <BR> - **Wrong** paperclip or fullmoon |
121
-
|**prefixes and suffixes**||
122
-
|:heavy_check_mark:**MUST** suffix date and time properties with | - **Right:** dueDate — an Edm.Date <BR> - **Right:**createdDateTime — an Edm.DateTimeOffset <BR> - **Right:**recurringMeetingTime — an Edm.TimeOfDay <BR>- **Wrong** dueOn or startTime - <BR> - **Right:**instead both above are an Edm.DateTimeOffset |
123
-
|:ballot_box_with_check:**SHOULD** use the Duration type for durations, but if using an int, append the units. | - **Right:** passwordValidityPeriod — an Edm.Duration <BR> - **Right:** passwordValidityPeriodInDays — an Edm.Int32 (NOTE use of Edm.Duration type is preferable) <BR>- **Wrong** passwordValidityPeriod — an Edm.Int32 |
124
-
|:no_entry:**MUST NOT** use suffix property names with primitive type names unless the type is temporal. | - **Right:** isEnabled or amount <BR> - **Wrong** enabledBool |
125
-
|:ballot_box_with_check:**SHOULD** prefix property names for properties concerning a different entity. | - **Right:** siteWebUrl on driveItem, or userId on auditActor <BR> - **Wrong** webUrl on contact when its the companyWebUrl |
126
-
|:ballot_box_with_check:**SHOULD** prefix Boolean properties with is, unless this leads to awkward or unnatural sounding names for Boolean properties. | - **Right:** isEnabled or isResourceAccount <BR>- **Wrong** enabled or allowResourceAccount <BR> - **Right:** allowNewTimeProposals or allowInvitesFrom — subjectively more natural than the following examples <BR> - **Wrong** isNewTimeProposalsAllowed or isInvitesFromAllowed — subjectively more awkward that the preceding examples |
|:no_entry:**MUST NOT** use redundant words in names. | - **Right:** /places/{id}/**displayName**or /phones/{id}/**number** <BR> - **Wrong:** /places/{id}/**placeName** or /phones/{id}/**phoneNumber**|
109
+
|:warning:**SHOULD NOT** use brand names in type or property names. | - **Right:** chat <BR> - **Wrong:** teamsChat |
110
+
|:warning:**SHOULD NOT** use acronyms or abbreviations unless they are broadly understood. | - **Right:** url or htmlSignature <BR> - **Wrong:** msodsUrl or dlp |
111
+
|:heavy_check_mark:**MUST** use singular nouns for type names. | - **Right:** address <BR> - **Wrong:** addresses |
112
+
|:heavy_check_mark:**MUST** use plural nouns for collections (for listing type or collection properties). | - **Right:** addresses <BR> - **Wrong:** address |
113
+
|:ballot_box_with_check:**SHOULD** pluralize the noun even when followed by an adjective (a *postpositive*).| - **Right:** passersby or mothersInLaw <BR> - **Wrong:** notaryPublics or motherInLaws |
114
+
|**CASING**||
115
+
|:heavy_check_mark:**MUST** use lower camel case for *all* names and namespaces.| - **Right:** automaticRepliesStatus <BR> - **Wrong:** kebab-case or snake_case |
116
+
|:ballot_box_with_check:**SHOULD** case two-letter acronyms with the same case. | - **Right:** ioLimit or totalIOAmount <BR> - **Wrong:** iOLimit or totalIoAmount |
117
+
|:ballot_box_with_check:**SHOULD** case three+ letter acronyms the same as a normal word. | - **Right:** fidoKey or oauthUrl <BR> - **Wrong:** webHTML |
118
+
|:no_entry:**MUST NOT** capitalize the word following a [prefix](https://www.thoughtco.com/common-prefixes-in-english-1692724) or words within a [compound word](http://www.learningdifferences.com/Main%20Page/Topics/Compound%20Word%20Lists/Compound_Word_%20Lists_complete.htm). | - **Right:** subcategory, geocoordinate, or crosswalk <BR> - **Wrong:** metaData, semiCircle, or airPlane |
119
+
|:heavy_check_mark:**MUST** capitalize within hyphenated and open (spaced) compound words. | - **Right:** fiveYearOld, daughterInLaw, or postOffice <BR> - **Wrong:** paperclip or fullmoon |
120
+
|**PREFIXES AND SUFFIXES**||
121
+
|:heavy_check_mark:**MUST** suffix date and time properties with Date, Time, or DateTime | - **Right:** dueDate — an Edm.Date <BR> - **Right:**recurringMeetingTime — an Edm.TimeOfDay <BR> - **Right:**createdDateTime — an Edm.DateTimeOffset <BR>- **Wrong:** dueOn or startTime <BR> - **Right:**Instead, both of the preceding are an Edm.DateTimeOffset |
122
+
|:ballot_box_with_check:**SHOULD** use the Duration type for durations, but if using an `int`, append the units. | - **Right:** passwordValidityPeriod — an Edm.Duration <BR> - **Right:** passwordValidityPeriodInDays — an Edm.Int32 (use of Edm.Duration type is preferable) <BR>- **Wrong:** passwordValidityPeriod — an Edm.Int32 |
123
+
|:no_entry:**MUST NOT** use suffix property names with primitive type names unless the type is temporal. | - **Right:** isEnabled or amount <BR> - **Wrong:** enabledBool |
124
+
|:ballot_box_with_check:**SHOULD** prefix property names for properties concerning a different entity. | - **Right:** siteWebUrl on driveItem or userId on auditActor <BR> - **Wrong:** webUrl on contact when it's the companyWebUrl |
125
+
|:ballot_box_with_check:**SHOULD** prefix Boolean properties with `is`, unless this leads to awkward or unnatural sounding names for Boolean properties. | - **Right:** isEnabled or isResourceAccount <BR>- **Wrong:** enabled or allowResourceAccount <BR> - **Right:** allowNewTimeProposals or allowInvitesFrom (subjectively more natural than the following examples) <BR> - **Wrong:** isNewTimeProposalsAllowed or isInvitesFromAllowed (subjectively more awkward that the preceding examples)|
126
+
|:no_entry:**MUST NOT** use collection, response, or request suffixes. |- **Right:** addresses <BR> - **Wrong:** addressCollection |
0 commit comments