Skip to content

Commit 6cceee3

Browse files
OlgaPodoOlgaPodo
committed
moving to RFC 2119 conventions
1 parent 3924b28 commit 6cceee3

6 files changed

+246
-117
lines changed

‎graph/GuidelinesGraph.md

Lines changed: 19 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -133,35 +133,33 @@ identify potential error scenarios with secure and descriptive messaging.
133133
Consistent naming is foundational for API usability. API resources are typically
134134
described by nouns. You need to consider that resources and property names
135135
appear in API URLs and payloads and should be descriptive and easy to
136-
understand. Therefore you should satisfy the following requirements summarized in the table below:
136+
understand. Microsoft Graph naming conventions follow [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md). Below is a short summary of the most often used conventions.
137137
|Requirements|Example|
138138
|--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
139-
| :no_entry: **DO NOT** use redundant words in names. |- **Right:** /places/{id}/**type** and /phones/{id}/**number** <BR> - **Wrong** /places/{id}/*placeType* and /phones/{id}/**phoneNumber** |
140-
| :no_entry: **DO NOT** use brand names in type or property names. | - **Right:** chat <BR> - **Wrong** teamsChat |
141-
| :no_entry: **DO NOT** use acronyms or abbreviations unless they are broadly understood. | - **Right:** url or htmlSignature <BR> - **Wrong** msodsUrl or dlp |
142-
| :heavy_check_mark: **DO** use singular nouns for type names. | - **Right:** address <BR> - **Wrong** addresses |
143-
| :heavy_check_mark: **DO** use plural nouns for collections (for listing a type or collection properties). | - **Right:** addresses <BR> - **Wrong** address |
144-
| :heavy_check_mark: **DO** pluralize the noun even when followed by an adjective (a "postpositive"). | - **Right:** passersby or mothersInLaw <BR> - **Wrong** notaryPublics or motherInLaws |
145-
| :heavy_check_mark: **DO** name property as “email” | - **Right:** email <BR> - **Wrong** mail |
139+
| :no_entry: **MUST NOT** use redundant words in names. |- **Right:** /places/{id}/**type** and /phones/{id}/**number** <BR> - **Wrong** /places/{id}/*placeType* and /phones/{id}/**phoneNumber** |
140+
| :no_entry: **SHOULD NOT** use brand names in type or property names. | - **Right:** chat <BR> - **Wrong** teamsChat |
141+
| :no_entry: **SHOULD NOT** use acronyms or abbreviations unless they are broadly understood. | - **Right:** url or htmlSignature <BR> - **Wrong** msodsUrl or dlp |
142+
| :heavy_check_mark: **MUST** use singular nouns for type names. | - **Right:** address <BR> - **Wrong** addresses |
143+
| :heavy_check_mark: **MUST** use plural nouns for collections (for listing a type or collection properties). | - **Right:** addresses <BR> - **Wrong** address |
144+
| :heavy_check_mark: **SHOULD** pluralize the noun even when followed by an adjective (a "postpositive"). | - **Right:** passersby or mothersInLaw <BR> - **Wrong** notaryPublics or motherInLaws |
146145

147146
#### Casing
148147
|Requirements|Example|
149148
|--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
150-
| :heavy_check_mark: **DO** use lower camel case for *all* names and namespaces | - **Right:** automaticRepliesStatus. <BR> - **Wrong** kebab-case or snake_case. |
151-
| :heavy_check_mark: **DO** case two-letter acronyms with the same case. | - **Right:** ioLimit or totalIOAmount <BR> - **Wrong** iOLimit or totalIoAmount |
152-
| :heavy_check_mark: **DO** case three+ letter acronyms the same as a normal word. | - **Right:** fidoKey or oauthUrl <BR> - **Wrong** webHTML |
153-
|:no_entry: **DO 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 |
154-
| :heavy_check_mark: **DO** capitalize within hyphenated and open (spaced) compound words. | - **Right:** fiveYearOld, daughterInLaw or postOffice <BR> - **Wrong** paperclip or fullmoon |
149+
| :heavy_check_mark: **Must** use lower camel case for *all* names and namespaces | - **Right:** automaticRepliesStatus. <BR> - **Wrong** kebab-case or snake_case. |
150+
| :heavy_check_mark: **Should** case two-letter acronyms with the same case. | - **Right:** ioLimit or totalIOAmount <BR> - **Wrong** iOLimit or totalIoAmount |
151+
| :heavy_check_mark: **Should** case three+ letter acronyms the same as a normal word. | - **Right:** fidoKey or oauthUrl <BR> - **Wrong** webHTML |
152+
|: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 |
153+
| :heavy_check_mark: **MUST** capitalize within hyphenated and open (spaced) compound words. | - **Right:** fiveYearOld, daughterInLaw or postOffice <BR> - **Wrong** paperclip or fullmoon |
155154

156155
#### Prefixes and Suffixes
157156
|Requirements |Example|
158157
|----------------------------------------------------------|------------------------------------------------|
159-
| :heavy_check_mark: **DO** use namespaces | Microsoft Graph model types can be declared within a [type namespaces](./type-namespaces.md) to reduce the need to prefix types with a qualifier to ensure uniqueness. |
160-
| :heavy_check_mark: **DO** 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 |
161-
| :heavy_check_mark: **DO** 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|
162-
|:no_entry: **DO NOT** use suffix property names with primitive type names unless the type is temporal.| - **Right:** isEnabled or amount <BR> - **Wrong** enabledBool|
163-
| :heavy_check_mark: **DO** 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|
164-
| :heavy_check_mark: **DO** 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 allowResourcAccount <BR> - **Right:** allowNewTimeProposals or allowInvitesFrom — subjectively more natural than the examples below • <BR> - **Wrong** isNewTimeProposalsAllowed or isInvitesFromAllowed — subjectively more awkward that the examples above |
158+
| :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 |
159+
| :heavy_check_mark: **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|
160+
|:no_entry: **MUST NOT** use suffix property names with primitive type names unless the type is temporal.| - **Right:** isEnabled or amount <BR> - **Wrong** enabledBool|
161+
| :heavy_check_mark: **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|
162+
| :heavy_check_mark: **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 allowResourcAccount <BR> - **Right:** allowNewTimeProposals or allowInvitesFrom — subjectively more natural than the examples below • <BR> - **Wrong** isNewTimeProposalsAllowed or isInvitesFromAllowed — subjectively more awkward that the examples above |
165163

166164
### Uniform Resource Locators (URLs)
167165

@@ -170,7 +168,7 @@ API.
170168

171169
Navigation path to the Microsoft Graph resources generally broken into multiple segments:
172170

173-
**{scheme}://{host}/{version}/{category}/{resourcePath}[?{query}]** where
171+
**{scheme}://{host}/{version}/{category}/[{pathSegment}][?{query}]** where
174172

175173
- **scheme and host segments** are always
176174
[https://graph.microsoft.com](https://graph.microsoft.com/v1.0/users);
@@ -183,7 +181,7 @@ Navigation path to the Microsoft Graph resources generally broken into multiple
183181
- **resourcePath** segment can address an entity, collection of entities,
184182
property or operation available for an entity. Structure of the resource
185183
path is covered in detail in the [OData Version 4.01. Part 2: URL
186-
Conventions](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html);
184+
Conventions](https://github.com/microsoft/api-guidelines/blob/op-graphPatterns/Guidelines.md#93-collection-url-patterns);
187185

188186
- **query string** must follow the OData standard for query representations
189187
and is covered in [Query](#query) section.

0 commit comments

Comments
 (0)