updated collections

Author: OlgaPodo

graph/GuidelinesGraph.md

@@ -277,11 +277,10 @@ For an additional list of standard HTTP methods, see the [RFC7230](https://www.r
     "code": "badRequest",
     "message": "Cannot process the request because a required field is missing.",
     "target": "query",    
-    "innererror": {
-                "code": "requiredFieldMissing",
-                           
-                }
-    }
+    "innererror":{
+      "code": "requiredFieldMissing",
+      "message": "A required field is missing.",                  
+     }
 }
 ```
 
@@ -308,7 +307,7 @@ The top-level error code MUST match the HTTP response status code description, c
         "message": "Cannot process the request because it is malformed or incorrect.",
         "innererror": {
           "code": "requiredFieldOrParameterMissing",
-               
+          "message": "A required field or parameter is missing.",               
         }
       }
     }

graph/articles/collections.md

@@ -1,55 +1,72 @@
-#  Collections
+# Collections
+
 ## 1. Item keys
-Services MAY support durable identifiers for each item in the collection, and that identifier SHOULD be represented in JSON as "id". These durable identifiers are often used as item keys.
 
-Collections that support durable identifiers MAY support delta queries.
+Services SHOULD support durable identifiers for each item in the collection, and that identifier SHOULD be represented in JSON as "id". These durable identifiers are often used as item keys.
+
+Collections MAY support delta queries, see the [Change Tracking pattern](../patterns/change-tracking.md) section for more details.
 
 ## 2. Serialization
-Collections are represented in JSON using standard array notation.
+
+Collections are represented in JSON using standard array notation for `value` property. 
 
 ## 3. Collection URL patterns
-Collections are located directly under the service root when they are top-level, or as a segment under another resource when scoped to that resource. Collection names usually use plural nouns with no suffixes, such as "Collection" or "List".
+
+While there are multiple collections located directly under the Graph root going forward, you MUST have a singleton for the top-level segment and scope collections to an appropriate singleton. Collection names SHOULD be plural nouns when possible. Collection names shouldn't use suffixes, such as "Collection" or "List".
 
 For example:
 
 ```http
-GET https://api.contoso.com/v1.0/people
+GET https://graph.microsoft.com/v1.0/teamwork/devices
 ```
 
-<mark> Whenever possible, services MUST support the "/" pattern.</mark>
+Collections elements MUST be addressable by a unique id property. The id property MUST be a String and MUST be unique within the collection. The id property MUST be represented in JSON as "id".
 For example:
 
 ```http
-GET https://{serviceRoot}/{collection}/{id}
+GET https://graph.microsoft.com/beta/teamwork/devices/0f3ce432-e432-0f3c-32e4-3c0f32e43c0f
 ```
 
 Where:
-- {serviceRoot} – the combination of host (site URL) + the root path to the service
-- {collection} – the name of the collection, unabbreviated, pluralized
-- {id} – the value of the unique id property. When using the "/" pattern this MUST be the raw string/number/guid value with no quoting but properly escaped to fit in a URL segment.
+
+- "https://graph.microsoft.com/beta/teamwork" - the service root represented as the combination of host (site URL) + the root path to the service.
+- "devices" – the name of the collection, unabbreviated, pluralized.
+- "0f3ce432-e432-0f3c-32e4-3c0f32e43c0f" – the value of the unique id property that MUST be the raw string/number/guid value with no quoting but properly escaped to fit in a URL segment.
 
 ### 3.1. Nested collections and properties
+
 Collection items MAY contain other collections.
-For example, a user collection MAY contain user resources that have multiple addresses:
+For example, a devices collection MAY contain device resources that have multiple mac addresses:
 
 ```http
-GET https://api.contoso.com/v1.0/people/123/addresses
+GET https://graph.microsoft.com/beta/teamwork/devices/0f3ce432-e432-0f3c-32e4-3c0f32e43c0f
 ```
 
 ```json
+
 {
-  "value": [
-    { "street": "1st Avenue", "city": "Seattle" },
-    { "street": "124th Ave NE", "city": "Redmond" }
-  ]
+  "value": {
+    "@odata.type": "#microsoft.graph.teamworkDevice",
+    "id": "0f3ce432-e432-0f3c-32e4-3c0f32e43c0f",
+    "deviceType": "CollaborationBar",
+    "hardwareDetail": {
+      "serialNumber": "0189",
+      "uniqueId": "5abcdefgh",
+      "macAddresses": [],
+      "manufacturer": "yealink",
+      "model": "vc210"
+    },
+    ...    
+  }
 }
 ```
 
 ## 4. Big collections
+
 As data grows, so do collections.
-Planning for pagination is important for all services.
-Therefore, when multiple pages are available, the serialization payload MUST contain the opaque URL for the next page as appropriate.
-Refer to the paging guidance for more details.
+Services SHOULD support server-side pagination from day one even for all collections, as adding pagination is a breaking change.
+When multiple pages are available, the serialization payload MUST contain the opaque URL for the next page as appropriate.
+Refer to the [paging guidance](../Guidelines-deprecated.md#98-pagination) for more details.
 
 Clients MUST be resilient to collection data being either paged or nonpaged for any given request.
 
@@ -66,37 +83,34 @@ Clients MUST be resilient to collection data being either paged or nonpaged for
 ```
 
 ## 5. Changing collections
+
 POST requests are not idempotent.
 This means that two POST requests sent to a collection resource with exactly the same payload MAY lead to multiple items being created in that collection.
 This is often the case for insert operations on items with a server-side generated id.
+For additional information refer to [Upsert pattern](../patterns/upsert.md).
 
 For example, the following request:
 
 ```http
-POST https://api.contoso.com/v1.0/people
-```
+POST https://graph.microsoft.com/beta/teamwork/devices
 
 Would lead to a response indicating the location of the new collection item:
 
 ```http
 201 Created
-Location: https://api.contoso.com/v1.0/people/123
+Location: https://graph.microsoft.com/beta/teamwork/devices/123
 ```
 
 And once executed again, would likely lead to another resource:
 
 ```http
 201 Created
-Location: https://api.contoso.com/v1.0/people/124
+Location: https://graph.microsoft.com/beta/teamwork/devices/124
 ```
 
-While a PUT request would require the indication of the collection item with the corresponding key instead:
-
-```http
-PUT https://api.contoso.com/v1.0/people/123
-```
 
 ## 6. Sorting collections
+
 The results of a collection query MAY be sorted based on property values.
 The property is determined by the value of the _$orderBy_ query parameter.
 
@@ -114,56 +128,54 @@ The sort order is the inherent order for the type of the property.
 For example:
 
 ```http
-GET https://api.contoso.com/v1.0/people?$orderBy=name
+GET https://graph.microsoft.com/beta/teamwork/devices?$orderBy=companyAssetTag
 ```
 
-Will return all people sorted by name in ascending order.
+Will return all devices sorted by companyAssetTag in ascending order.
 
 For example:
 
 ```http
-GET https://api.contoso.com/v1.0/people?$orderBy=name desc
+GET https://graph.microsoft.com/beta/teamwork/devices?$orderBy=companyAssetTag desc
 ```
 
-Will return all people sorted by name in descending order.
+Will return all devices sorted by companyAssetTag in descending order.
 
 Sub-sorts can be specified by a comma-separated list of property names with OPTIONAL direction qualifier.
 
 For example:
 
 ```http
-GET https://api.contoso.com/v1.0/people?$orderBy=name desc,hireDate
+GET https://graph.microsoft.com/beta/teamwork/devices?$orderBy=companyAssetTag desc,activityState
 ```
 
-Will return all people sorted by name in descending order and a secondary sort order of hireDate in ascending order.
-
-Sorting MUST compose with filtering such that:
+Will return all devices sorted by companyAssetTag in descending order and a secondary sort order of activityState in ascending order.
 
-```http
-GET https://api.contoso.com/v1.0/people?$filter=name eq 'david'&$orderBy=hireDate
-```
+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.
 
-Will return all people whose name is David sorted in ascending order by hireDate.
 
 ### 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.
 
 If a service does not support sorting by a property named in a _$orderBy_ expression, the service MUST respond with an error message as defined in the Responding to Unsupported Requests section.
 
 ## 7. Filtering
+
 The _$filter_ querystring parameter allows clients to filter a collection of resources that are addressed by a request URL.
 The expression specified with _$filter_ is evaluated for each resource in the collection, and only items where the expression evaluates to true are included in the response.
 Resources for which the expression evaluates to false or to null, or which reference properties that are unavailable due to permissions, are omitted from the response.
 
-Example: return all Products whose Price is less than $10.00
+Example: return all devices with activity state equal to 'Active'
 
 ```http
-GET https://api.contoso.com/v1.0/products?$filter=price lt 10.00
+GET https://graph.microsoft.com/beta/teamwork/devices?$filter=(activityState eq 'Active') 
 ```
 
 The value of the _$filter_ option is a Boolean expression.
 
 ### 7.1. Filter operations
+
 Services that support _$filter_ SHOULD support the following minimal set of operations.
 
 Operator             | Description           | Example
@@ -182,40 +194,6 @@ not                  | Logical negation      | not price le 3.5
 Grouping Operators   |                       |
 ( )                  | Precedence grouping   | (priority eq 1 or city eq 'Redmond') and price gt 100
 
-### 7.2. Operator examples
-The following examples illustrate the use and semantics of each of the logical operators.
-
-Example: all products with a name equal to 'Milk'
-
-```http
-GET https://api.contoso.com/v1.0/products?$filter=name eq 'Milk'
-```
-
-Example: all products with a name not equal to 'Milk'
-
-```http
-GET https://api.contoso.com/v1.0/products?$filter=name ne 'Milk'
-```
-
-Example: all products with the name 'Milk' that also have a price less than 2.55:
-
-```http
-GET https://api.contoso.com/v1.0/products?$filter=name eq 'Milk' and price lt 2.55
-```
-
-Example: all products that either have the name 'Milk' or have a price less than 2.55:
-
-```http
-GET https://api.contoso.com/v1.0/products?$filter=name eq 'Milk' or price lt 2.55
-```
-
-Example: all products that have the name 'Milk' or 'Eggs' and have a price less than 2.55:
-
-```http
-GET https://api.contoso.com/v1.0/products?$filter=(name eq 'Milk' or name eq 'Eggs') and price lt 2.55
-```
-
-### 7.3. Operator precedence
 Services MUST use the following operator precedence for supported operators when evaluating _$filter_ expressions.
 Operators are listed by category in order of precedence from highest to lowest.
 Operators in the same category have equal precedence:
@@ -225,15 +203,16 @@ Operators in the same category have equal precedence:
 | Grouping        | ( )      | Precedence grouping   |
 | Unary           | not      | Logical Negation      |
 | Relational      | gt       | Greater Than          |
-|                 | ge       | Greater than or Equal |
+|                 | ge       | Greater Than or Equal |
 |                 | lt       | Less Than             |
-|                 | le       | Less than or Equal    |
+|                 | le       | Less Than or Equal    |
 | Equality        | eq       | Equal                 |
 |                 | ne       | Not Equal             |
 | Conditional AND | and      | Logical And           |
 | Conditional OR  | or       | Logical Or            |
 
 ## 8. Pagination
+
 RESTful APIs that return collections MAY return partial sets.
 Consumers of these services MUST expect partial result sets and correctly page through to retrieve an entire set.
 
@@ -244,6 +223,7 @@ Client-driven paging enables clients to request only the number of resources tha
 Sorting and Filtering parameters MUST be consistent across pages, because both client- and server-side paging is fully compatible with both filtering and sorting.
 
 ### 8.1. Server-driven paging
+
 Paginated responses MUST indicate a partial result by including a continuation token in the response.
 The absence of a continuation token means that no additional pages are available.
 
@@ -252,20 +232,20 @@ Clients MUST treat the continuation URL as opaque, which means that query option
 Example:
 
 ```http
-GET http://api.contoso.com/v1.0/people HTTP/1.1
+GET https://graph.microsoft.com/beta/teamwork/devices
 Accept: application/json
 
 HTTP/1.1 200 OK
 Content-Type: application/json
 
 {
-  ...,
   "value": [...],
   "@nextLink": "{opaqueUrl}"
 }
 ```
 
 ### 8.2. Client-driven paging
+
 Clients MAY use _$top_ and _$skip_ query parameters to specify a number of results to return and an offset into the collection.
 
 The server SHOULD honor the values specified by the client; however, clients MUST be prepared to handle responses that contain a different page size or contain a continuation token.
@@ -278,19 +258,20 @@ This will avoid the risk of the client making assumptions about the data returne
 Example:
 
 ```http
-GET http://api.contoso.com/v1.0/people?$top=5&$skip=2 HTTP/1.1
+GET https://graph.microsoft.com/beta/teamwork/devices?$top=5&$skip=2 
+
 Accept: application/json
 
 HTTP/1.1 200 OK
 Content-Type: application/json
 
 {
-  ...,
-  "value": [...]
+   "value": [...]
 }
 ```
 
 ### 8.3. Additional considerations
+
 **Stable order prerequisite:** Both forms of paging depend on the collection of items having a stable order.
 The server MUST supplement any specified order criteria with additional sorts (typically by key) to ensure that items are always ordered consistently.
 
@@ -310,31 +291,29 @@ If a server paginates an embedded collection, it MUST include additional continu
 **Recordset count:** Developers who want to know the full number of records across all pages, MAY include the query parameter _$count=true_ to tell the server to include the count of items in the response.
 
 ## 9. Compound collection operations
+
 Filtering, Sorting and Pagination operations MAY all be performed against a given collection.
 When these operations are performed together, the evaluation order MUST be:
 
 1. **Filtering**. This includes all range expressions performed as an AND operation.
 2. **Sorting**. The potentially filtered list is sorted according to the sort criteria.
 3. **Pagination**. The materialized paginated view is presented over the filtered, sorted list. This applies to both server-driven pagination and client-driven pagination.
-<mark>
+
 ## 10. Empty Results
-</mark>
+
 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. 
-<mark>A client MAY be expecting metadata attributes like _maxItems_ based on the format of your responses to similar calls which produced results.<mark> 
-You SHOULD maintain consistency in your API whenever possible. 
+You SHOULD maintain consistency in your API whenever possible.
 
 ```http
-GET https://api.contoso.com/v1.0/products?$filter=(name eq 'Milk' or name eq 'Eggs') and price lt 2.55
+GET https://graph.microsoft.com/beta/teamwork/devices?$filter=('deviceType'  eq 'Collab' or companyAssetTa eq 'Tag1')
 Accept: application/json
 
 HTTP/1.1 200 OK
 Content-Type: application/json
 
 {
-  ...,
-  "maxItems": 0,
-  "value": []
+   "value": []
 }
 ```