formatting

Author: OlgaPodo

graph/articles/collections.md

@@ -8,7 +8,7 @@ Collections MAY support delta queries, see the [Change Tracking pattern](../patt
 
 ## 2. Serialization
 
-Collections are represented in JSON using standard array notation for `value` property. 
+Collections are represented in JSON using standard array notation for `value` property.
 
 ## 3. Collection URL patterns
 
@@ -108,7 +108,6 @@ And once executed again, would likely lead to another resource:
 Location: https://graph.microsoft.com/beta/teamwork/devices/124
 ```
 
-
 ## 6. Sorting collections
 
 The results of a collection query MAY be sorted based on property values.
@@ -153,7 +152,6 @@ Will return all devices sorted by companyAssetTag in descending order and a seco
 
 Sorting MUST compose with filtering see [Odata 4.01 spec](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#_Toc31361038) for more details.
 
-
 ### 6.1. Interpreting a sorting expression
 
 Sorting parameters MUST be consistent across pages, as both client and server-side paging is fully compatible with sorting.
@@ -301,9 +299,9 @@ When these operations are performed together, the evaluation order MUST be:
 
 ## 10. Empty Results
 
-When a filter is performed on a collection and the result set is empty you MUST respond with a valid response body and a 200 response code. 
-In this example the filters supplied by the client resulted in a empty result set. 
-The response body is returned as normal and the _value_ attribute is set to a empty collection. 
+When a filter is performed on a collection and the result set is empty you MUST respond with a valid response body and a 200 response code.
+In this example the filters supplied by the client resulted in a empty result set.
+The response body is returned as normal and the _value_ attribute is set to a empty collection.
 You SHOULD maintain consistency in your API whenever possible.
 
 ```http

graph/articles/errorResponses.md

@@ -21,7 +21,7 @@ Services can avoid breaking changes by adding new error codes to "innererror" in
 
 The value for the "message" name/value pair MUST be a human-readable representation of the error.
 It is intended as an aid to developers and is not suitable for exposure to end users.
-Services wanting to expose a suitable message for end users MUST do so through an [annotation][odata-json-annotations] or custom property.
+Services wanting to expose a suitable message for end users MUST do so through an [odata-json-annotations](https://docs.oasis-open.org/odata/odata-json-format/v4.01/cs02/odata-json-format-v4.01-cs02.html#sec_AnnotateaJSONObject) or custom property.
 Services SHOULD NOT localize "message" for the end user, because doing so might make the value unreadable to the app developer who may be logging the value, as well as make the value less searchable on the Internet.
 
 The value for the "target" name/value pair is the target of the particular error (e.g., the name of the property in error).
@@ -42,17 +42,17 @@ Error objects MAY also include custom server-defined name/value pairs that MAY b
 Error types with custom server-defined properties SHOULD be declared in the service's metadata document.
 See example below.
 
-Error responses MAY contain [annotations][odata-json-annotations] in any of their JSON objects.
+Error responses MAY contain Odata JSON annotations in any of their JSON objects.
 
 We recommend that for any transient errors that may be retried, services SHOULD include a Retry-After HTTP header indicating the minimum number of seconds that clients SHOULD wait before attempting the operation again.
 
-##### ErrorResponse : Object
+## ErrorResponse : Object
 
 Property | Type | Required | Description
 -------- | ---- | -------- | -----------
 `error` | Error | ✔ | The error object.
 
-##### Error : Object
+## Error : Object
 
 Property | Type | Required | Description
 -------- | ---- | -------- | -----------
@@ -62,14 +62,14 @@ Property | Type | Required | Description
 `details` | Error[] |  | An array of details about specific errors that led to this reported error.
 `innererror` | InnerError |  | An object containing more specific information than the current object about the error.
 
-##### InnerError : Object
+## InnerError : Object
 
 Property | Type | Required | Description
 -------- | ---- | -------- | -----------
 `code` | String |  | A more specific error code than was provided by the containing error.
 `innererror` | InnerError |  | An object containing more specific information than the current object about the error.
 
-##### Examples
+## Examples
 
 Example of "innererror":
 

graph/articles/naming.md

@@ -1,51 +1,61 @@
-#  Naming 
-##  1. Approach
+# Naming
+
+## 1. Approach
+
 Naming policies should aid developers in discovering functionality without having to constantly refer to documentation.
 Use of common patterns and standard conventions greatly aids developers in correctly guessing common property names and meanings.
 Services SHOULD use verbose naming patterns and MUST NOT use abbreviations other than acronyms that are the dominant mode of expression in the domain being represented by the API, (e.g. Url).
 
-##  2. Casing
+## 2. Casing
+
 - Acronyms SHOULD follow the casing conventions as though they were regular words (e.g. Url).
 - All identifiers including namespaces, entityTypes, entitySets, properties, actions, functions and enumeration values MUST use lowerCamelCase.
 - HTTP headers are the exception and SHOULD use standard HTTP convention of Capitalized-Hyphenated-Terms.
 
-##  3. Names to avoid
+## 3. Names to avoid
+
 Certain names are so overloaded in API domains that they lose all meaning or clash with other common usages in domains that cannot be avoided when using REST APIs, such as OAUTH.
 Services SHOULD NOT use the following names:
+
 - Context
 - Scope
 - Resource
 
-##  4. Forming compound names
+## 4. Forming compound names
+
 - Services SHOULD avoid using articles such as 'a', 'the', 'of' unless needed to convey meaning.
-	- e.g. names such as aUser, theAccount, countOfBooks SHOULD NOT be used, rather user, account, bookCount SHOULD be preferred.
+  - e.g. names such as aUser, theAccount, countOfBooks SHOULD NOT be used, rather user, account, bookCount SHOULD be preferred.
 - Services SHOULD add a type to a property name when not doing so would cause ambiguity about how the data is represented or would cause the service not to use a common property name.
 - When adding a type to a property name, services MUST add the type at the end, e.g. createdDateTime.
 
-##  5. Identity properties
+## 5. Identity properties
+
 - Services MUST use string types for identity properties.
 - For OData services, the service MUST use the OData @id property to represent the canonical identifier of the resource.
 - Services MAY use the simple 'id' property to represent a local or legacy primary key value for a resource.
 - Services SHOULD use the name of the relationship postfixed with 'Id' to represent a foreign key to another resource, e.g. subscriptionId.
-	- The content of this property SHOULD be the canonical ID of the referenced resource.
+  - The content of this property SHOULD be the canonical ID of the referenced resource.
 
-##  6. Date and time properties
+## 6. Date and time properties
 
 - For properties requiring both date and time, services MUST use the suffix 'DateTime'.
 - For properties requiring only date information without specifying time, services MUST use the suffix 'Date', e.g. birthDate.
 - For properties requiring only time information without specifying date, services MUST use the suffix 'Time', e.g. appointmentStartTime.
 
-##  7. Name properties
+## 7. Name properties
+
 - For the overall name of a resource typically shown to users, services MUST use the property name 'displayName'.
 - Services MAY use other common naming properties, e.g. givenName, surname, signInName.
 
-##  8. Collections and counts
+## 8. Collections and counts
+
 - Services MUST name collections as plural nouns or plural noun phrases using correct English.
 - Services MAY use simplified English for nouns that have plurals not in common verbal usage.
-	- e.g. schemas MAY be used instead of schemata.
+  - e.g. schemas MAY be used instead of schemata.
 - Services MUST name counts of resources with a noun or noun phrase suffixed with 'Count'.
 
-##  9. Common property names
+## 9. Common property names
+
 Where services have a property, whose data matches the names below, the service MUST use the name from this table.
 This table will grow as services add terms that will be more commonly used.
 Service owners adding such terms SHOULD propose additions to this document.