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
+10-10Lines changed: 10 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -90,7 +90,7 @@ At every step of your design, you need to consider security, privacy, and compli
90
90
91
91
### Naming
92
92
93
-
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 naming guidelines](Guidelines-deprecated.md#17-naming-guidelines).
93
+
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 naming guidelines](./articles/naming.md).
94
94
95
95
Following is a short summary of the most often used conventions.
96
96
@@ -104,7 +104,7 @@ Following is a short summary of the most often used conventions.
104
104
|: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 |
105
105
|**CASING**||
106
106
|:heavy_check_mark:**MUST** use lower camel case for *all* names and namespaces. | - **Right:** automaticRepliesStatus <BR> - **Wrong:** kebab-case or snake_case |
107
-
|:ballot_box_with_check:**SHOULD** case two-letter acronyms with the same case. | - **Right:** ioLimit or totalIOAmount <BR> - **Wrong:** iOLimit or totalIoAmount|
107
+
|:ballot_box_with_check:**SHOULD** case two-letter acronyms with the same case. | - **Right:** ioLimit or totalIOAmount <BR> - **Wrong:** iOLimit or totalIoAmount<BR> - **Exception:** ID properties similar to driveId or applicationId|
108
108
|:ballot_box_with_check:**SHOULD** case three+ letter acronyms the same as a normal word. | - **Right:** fidoKey or oauthUrl <BR> - **Wrong:** webHTML |
109
109
|: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, geo coordinate, or crosswalk <BR> - **Wrong:** metaData, semiCircle, or airPlane |
110
110
|:heavy_check_mark:**MUST** capitalize within hyphenated and open (spaced) compound words. | - **Right:** fiveYearOld, daughterInLaw, or postOffice <BR> - **Wrong:** paperclip or fullmoon |
@@ -154,7 +154,7 @@ Effectively, top-level categories define a perimeter for the API surface; thus,
154
154
155
155
You can model structured resources for your APIs by using the OData entity type or complex type. The main difference between these types is that an entity type declares a key property to uniquely identify its objects, and a complex type doesn't. In Microsoft Graph, this key property is called `id` for server-created key values. If there's a natural name for the key property, then the workload can use that.
156
156
157
-
Because objects of complex types in Microsoft Graph don’t have unique identifiers, they are not directly addressable via URIs. Therefore, you must use entity types to model addressable resources such as individually addressable items within a collection. For more information, see the [Collection URL patterns](Guidelines-deprecated.md#93-collection-url-patterns). Complex types are better suited to represent composite properties of API entities.
157
+
Because objects of complex types in Microsoft Graph don’t have unique identifiers, they are not directly addressable via URIs. Therefore, you must use entity types to model addressable resources such as individually addressable items within a collection. For more information, see the [Collection URL patterns](./articles/collections.md#3-collection-url-patterns). Complex types are better suited to represent composite properties of API entities.
158
158
159
159
```xml
160
160
<EntityTypeName="author">
@@ -230,16 +230,16 @@ See [Nullable properties](./articles/nullable.md) for more details.
230
230
231
231
### Query support
232
232
233
-
Microsoft Graph APIs returning collections of resources should support basic query options in conformance with [OData specifications](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_PassingQueryOptionsintheRequestBody) and [Collection Guidance](Guidelines-deprecated.md#9-collections).
233
+
Microsoft Graph APIs returning collections of resources should support basic query options in conformance with [OData specifications](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_PassingQueryOptionsintheRequestBody) and [Collection Guidance](./articles/collections.md).
|:heavy_check_mark:**MUST** support `$select on resource` to enable properties projection. |
238
238
|:ballot_box_with_check:**SHOULD** support `/entityTypeCollection/{id}?$expand=navProp1` option for navigation properties of entities. |
239
239
|:ballot_box_with_check:**SHOULD** support `$filter` with `eq` and `ne` operations on properties of entity collections. |
240
240
|:heavy_check_mark:**MUST** support pagination of collections (of entity types or complex types) using a [nextLink](http://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html#sec_ControlInformationnextLinkodatanextL). |
241
-
|:ballot_box_with_check:**MAY** support [server-driven pagination](Guidelines-deprecated.md#981-server-driven-paging) of collections using `$skiptoken`. |
242
-
|:ballot_box_with_check:**SHOULD** support [client-driven pagination](Guidelines-deprecated.md#982-client-driven-paging) of collections using `$top` and `$skip`. |
241
+
|:ballot_box_with_check:**MAY** support [server-driven pagination](./articles/collections.md#81-server-driven-paging) of collections using `$skiptoken`. |
242
+
|:ballot_box_with_check:**SHOULD** support [client-driven pagination](./articles/collections.md#82-client-driven-paging) of collections using `$top` and `$skip`. |
243
243
|:ballot_box_with_check:**SHOULD** support `$count` for collections. |
244
244
|:ballot_box_with_check:**SHOULD** support sorting with `$orderby` both ascending and descending on properties of the entities. |
245
245
@@ -252,7 +252,7 @@ Another way to avoid this is to use JSON batch as described in the [Microsoft Gr
252
252
253
253
The HTTP operations dictate how your API behaves. The URL of an API, along with its request/response bodies, establishes the overall contract that developers have with your service. As an API provider, how you manage the overall request/response pattern should be one of the first implementation decisions you make.
254
254
255
-
If possible, APIs SHOULD use resource-based designs with standard HTTP methods rather than operation resources. Operation resources are either functions or actions. According to [OData standards](http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part3-csdl/odata-v4.0-errata03-os-part3-csdl-complete.html#_The_edm:Function_Element_2), a function represents an operation that returns a single instance or collection of instances of any type and doesn’t have an observable side effect. An action might have side effects and might return a result represented as a single entity or collection of any type.
255
+
If possible, APIs SHOULD use resource-based designs with standard HTTP methods rather than operation resources. Operation resources are either functions or actions. According to [OData standards](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#_Toc31359009), a function represents an operation that returns a single instance or collection of instances of any type and doesn’t have an observable side effect. An action might have side effects and might return a result represented as a single entity or collection of any type.
0 commit comments