Skip to content

Commit ef4d909

Browse files
OlgaPodoOlgaPodo
committed
Merge branch 'vNext' into op_LRO
2 parents c7467f9 + 1929dfe commit ef4d909

File tree

4 files changed

+267
-113
lines changed

4 files changed

+267
-113
lines changed

‎graph/patterns/facets.md

Lines changed: 15 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,33 @@
1-
# Facets Pattern
1+
# Facets
22

33
Microsoft Graph API Design Pattern
44

5-
### *A frequent pattern in Microsoft Graph is to model multiple variants of a common concept as a single entity type with common properties and facets for variants.*
6-
5+
*A frequent pattern in Microsoft Graph is to model multiple variants of a common concept as a single entity type with common properties and facets for variants.*
76

87
## Problem
9-
API designer needs to model a set of heterogeneous resources that have common properties and behaviors, and may express features of multiple variants at a time because variants are not mutually exclusive.
10-
For example a movie clip stored on OneDrive is both a file and a video. There are properties associated to each variant.
8+
9+
An API designer needs to model a set of heterogeneous resources that have common properties and behaviors and might express features of multiple variants at a time because variants are not mutually exclusive.
10+
For example, a movie clip stored on OneDrive is both a file and a video. There are properties associated to each variant.
1111

1212
## Solution
1313

14-
API designers create multiple complex types to bundle properties for each variant then define an entity type with a property for each complex type to hold the properties of the variant.
15-
In this solution a child variant is identified by a presence of one or more facets in the parent object.
14+
API designers create multiple complex types to bundle properties for each variant, and then define an entity type with a property for each complex type to hold the properties of the variant.
1615

17-
## Issues and Considerations
16+
In this solution, a child variant is identified by the presence of one or more facets in the parent object.
1817

19-
When introducing a new facet, you need to ensure that the new facet doesn't change the semantic of the model with it's implicit constraints.
18+
## When to use this pattern
2019

20+
The facet pattern is useful when there is a number of variants and they are not mutually exclusive. It also makes it syntactically easier to query resources by using OData $filter expression because it doesn't require casting.
2121

22-
## When to Use this Pattern
22+
You can consider related patterns such as [Type hierarchy](./subtypes.md) and Flat bag of properties.
2323

24-
The facet pattern is useful when there is a number of variants and they are not mutually exclusive. It also makes syntactically easier to query resources using OData $filter expression since it doesn't require casting.
24+
## Issues and considerations
2525

26-
There are related patterns to consider such as
27-
[Type Hierarchy](https://github.com/microsoft/api-guidelines/tree/graph/graph) and [Flat
28-
bag of
29-
properties](https://github.com/microsoft/api-guidelines/tree/graph/graph).
26+
When introducing a new facet, you need to ensure that the new facet doesn't change the semantic of the model with its implicit constraints.
3027

3128
## Example
32-
The driveItem resource represents a file, folder,image or other item stored in a drive and is modeled using entity type with multiple facets.
29+
30+
The driveItem resource represents a file, folder, image, or other item stored in a drive and is modeled by using entity type with multiple facets.
3331

3432
```XML
3533

@@ -64,7 +62,7 @@ The driveItem resource represents a file, folder,image or other item stored in a
6462
</EntityType>
6563
```
6664

67-
API request to get all items from a personal OneDrive will return a heterogenous collection with different facets populated. In the example below there is a folder, a file and an image in the collection. The image entity has two facets populated: file and image.
65+
An API request to get all items from a personal OneDrive returns a heterogenous collection with different facets populated. In the following example, there is a folder, a file, and an image in the collection. The image entity has two facets populated: file and image.
6866

6967
```
7068
https://graph.microsoft.com/v1.0/me/drive/root/children

‎graph/patterns/namespace.md

Lines changed: 42 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -2,104 +2,88 @@
22

33
Microsoft Graph API Design Pattern
44

5-
*The Namespace provides the ability to organize resource definitions together into a logical set.*
5+
*The namespace pattern provides the ability to organize resource definitions together into a logical set.*
66

77
## Problem
88

9-
---
10-
When building a complex offering API designers may need to model many different
11-
resources and their relationships. For better user experience and
12-
discoverability related API elements need to be grouped together.
13-
9+
When building a complex offering, API designers might need to model many different
10+
resources and their relationships. For a better user experience and
11+
discoverability, related API elements need to be grouped together.
1412

1513
## Solution
1614

17-
---
18-
API designers can use the Namespace attribute of the CSDL schema to declare a
19-
namespace and logically organize related API entities in the Graph metadata.
15+
API designers can use the namespace attribute of the CSDL schema to declare a
16+
namespace and logically organize related API entities in the Microsoft Graph metadata.
2017

21-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ XML
18+
```XML
2219
<Schema Namespace="microsoft.graph.{namespace}">
2320
...
2421
</Schema>
25-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22+
```
2623

27-
A public namespace must have "microsoft.graph." prefix and be presented in camel
28-
case, i.e microsoft.graph.myNamespace.
24+
A public namespace must contain the `microsoft.graph.` prefix and be presented in camel
25+
case; that is, `microsoft.graph.myNamespace`.
2926

30-
When type casting is required in the API query, request or response, a fully
27+
When type casting is required in the API query, request, or response, a fully
3128
qualified type name is represented as concatenation of a namespace and a type
32-
name. For consistent user experience namespaces MUST be aligned with the corresponding API category path segment.
33-
34-
35-
## When to Use this Pattern
29+
name. For a consistent user experience, namespaces MUST be aligned with the corresponding API category path segment.
3630

37-
---
38-
API resource grouping creates a user-friendly experience keeping all resources
39-
for a specific feature close together
40-
and limits the length of IDE prompts such as auto-complete in some programming languages.
31+
## When to use this pattern
4132

42-
We recommend that a new namespace should be aligned with top-level API category.
33+
API resource grouping creates a user-friendly experience, keeping all resources for a specific feature close together and limiting the length of IDE prompts such as auto-complete in some programming languages.
4334

44-
## Issues and Considerations
35+
We recommend that a new namespace be aligned with a top-level API category.
4536

46-
---
47-
1. Microsoft Graph consistency requirements discourage using the same type
48-
names for different concepts even within different namespaces. Microsoft
49-
Graph type names must be descriptive and unique within the API
50-
surface without requiring full qualification.
37+
## Issues and considerations
5138

52-
2. Namespace must be consistent with API category in the navigation path according to [Microsoft Graph REST API Guidelines](GuidelinesGraph.md#uniform-resource-locators-urls)
39+
- Microsoft Graph consistency requirements discourage using the same type names for different concepts even within different namespaces. Microsoft Graph type names must be descriptive and unique within the API surface without requiring full qualification.
5340

54-
3. When type name is ambiguous and requires a namespace qualifier, changing
55-
namespace is a breaking change.
41+
- A namespace must be consistent with an API category in the navigation path according to [Microsoft Graph REST API Guidelines](../GuidelinesGraph.md#uniform-resource-locators-urls).
5642

57-
4. To extend a type in a different schema, a service must declare that schema
58-
and the type in it. This is conceptually similar to .NET partial types.
43+
- When type name is ambiguous and requires a namespace qualifier, changing a namespace is a breaking change.
5944

60-
5. To reference a type in a different schema, simply refer to that type by
61-
fully qualified name (namespace + type name).
45+
- To extend a type in a different schema, a service must declare that schema and the type in it. This is conceptually similar to .NET partial types.
6246

63-
6. Cyclical references between namespaces are not allowed as many
64-
object-oriented languages don’t support a cycles between namespaces.
47+
- To reference a type in a different schema, simply refer to that type by its fully qualified name (namespace + type name).
6548

66-
7. Microsoft Graph has some predefined constraints for declared namespaces:
49+
- Cyclical references between namespaces are not allowed because many object-oriented languages don’t support cycles between namespaces.
6750

68-
- All public namespaces must have a prefix "microsoft.graph"
51+
- Microsoft Graph has some predefined constraints for declared namespaces:
6952

70-
- Only one level of nesting deeper then "microsoft.graph" is supported
71-
72-
- If a namespace does not begin with "microsoft.graph" prefix, all types
73-
in the schema will be coerced into the main "microsoft.graph" namespace.
53+
- All public namespaces must have the prefix `microsoft.graph`.
54+
55+
- Only one level of nesting deeper than `microsoft.graph` is supported.
56+
57+
- If a namespace does not begin with the `microsoft.graph` prefix, all types in the schema are coerced into the main `microsoft.graph` namespace.
7458

7559
## Examples
7660

77-
---
78-
### Namespace and type declarations:
61+
### Namespace and type declarations
7962

80-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ XML
63+
```XML
8164
<Schema Namespace="microsoft.graph.search" xmlns=”<http://docs.oasis-open.org/odata/ns/edm>”\>
8265
…
8366
<EntityType Name="bookmark" …
8467
</EntityType>
8568
…
8669
</Schema>
87-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
70+
```
71+
72+
Fully qualified type name: `microsoft.graph.search.bookmark`
8873

89-
Fully qualified type name: "microsoft.graph.search.bookmark"
74+
### Managing multiple schemas
9075

91-
### Managing multiple schemas:
76+
Workloads must define schemas in their CSDL by using the Edmx format.
77+
Following is an example of a workload that exposes multiple namespaces.
9278

93-
Workloads must define schemas in their csdl using the Edmx format.
94-
Here is an example of a workload that exposes multiple namespaces.
79+
> **Tip:** As with schemas that exist in the `microsoft.graph` namespace, defining an
80+
entity type is optional; by default your schema derives all entity types
81+
from `microsoft.graph.entity`.
9582

96-
**Tip:** As with schemas that exist in the microsoft.graph namespace, defining an
97-
entity type is optional, by default your schema derives all entity types
98-
from microsoft.graph.entity.
83+
> **Warning:** Do not deviate from the general structure in the following example.
84+
The schema validation tool expects the XML structure (including XML namespace
85+
declarations) to match this example.
9986

100-
**Warning:** Do not deviate from the general structure in the example below.
101-
Schema validation tool expects the XML structure (including xml namespace
102-
declarations) to match the example below.
10387
```XML
10488
<?xml version="1.0" encoding="utf-8"?>
10589
<edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" xmlns:odata="http://schemas.microsoft.com/oDataCapabilities">

‎graph/patterns/subsets.md

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Modeling collection subsets
2+
3+
Microsoft Graph API Design Pattern
4+
5+
*The modeling collection subsets pattern is the modeling state associated to a collection that may include all instances, an included subset, an excluded subset, no instances, or any combinations of the preceding items.*
6+
7+
## Problem
8+
9+
A common pattern is to apply a policy or state to a collection of resources. With this, there also comes the question of how to model cases where we want to apply to `all` or `none` without having to special case these values within the collection set or introduce cross-property dependencies. Likewise, we'd like to model it in a way where it is easy to understand and interpret usage from just looking at the schema.
10+
11+
An example is where you have a policy that you need to be able to apply to users in an organization. You might want to support the default **None**, enablement for **All**, or enablement for **Select** users where you only grant it to a few users.
12+
13+
Existing patterns for this either have special-cased strings or have tightly coupled dependencies between two independent properties. Neither is intuitive, both require reading documentation, and neither can be inferred from the schema or within client libraries.
14+
15+
## Solution
16+
17+
Have an abstract base class where all variants of the subset are derived types from the base subset. For more information, see the [general subtyping guidance](./subtypes.md).
18+
19+
The abstract base class should also hold an enum for all possible variants. The purpose of including this is to allow for easier ways to do query and filter operations on variants like `all` and `none` without relying on `isof` functions.
20+
21+
**Base type**
22+
23+
```xml
24+
<ComplexType Name="membership" IsAbstract="true">
25+
<Property Name="membershipKind" Type="graph.membershipKind"/>
26+
</ComplexType>
27+
28+
<EnumType Name="membershipKind">
29+
<Member Name="all"/>
30+
<Member Name="enumerated"/>
31+
<Member Name="none"/>
32+
<Member Name="unknownFutureValue"/>
33+
</EnumType>
34+
```
35+
36+
**Derived types**
37+
38+
```xml
39+
<ComplexType Name="noMembership" BaseType="graph.membership"/>
40+
41+
<ComplexType Name="allMembership" BaseType="graph.membership"/>
42+
43+
<ComplexType Name="enumeratedMembership" BaseType = "graph.membership">
44+
<Property Name="members" Type="Collection(Edm.String)"/>
45+
</ComplexType>
46+
47+
<ComplexType Name="excludedMembership" BaseType="graph.membership">
48+
<Property Name="members" Type="Collection(Edm.String)"/>
49+
</ComplexType>
50+
```
51+
52+
Be aware that the name values and types in the preceding examples are just examples and can be replaced with your scenario equivalent values. For example, type names don't really need to be `memberships`. The collection doesn't have to be a collection at all; it can be singular and doesn't have to be a string.
53+
54+
These pattern type names should satisfy the following naming conventions:
55+
56+
- The base type name should have the suffix `Base`, and the enumeration type name should have the suffix `Kind`.
57+
- Derived child types should have names with enumeration values as the prefixes; for example, if the enumeration member value is `value1`, then the derived type name is `value1<type>`.
58+
59+
```xml
60+
<ComplexType Name="<type>Base" IsAbstract="true">
61+
<Property Name="<type>Kind" Type="graph.<type>Kind"/>
62+
</ComplexType>
63+
64+
<EnumType Name="<type>Kind">
65+
<Member Name="<value1>"/>
66+
<Member Name="<value2>"/>
67+
<Member Name="unknownFutureValue"/>
68+
</EnumType>
69+
70+
<ComplexType Name="value1<type>" BaseType="graph.<type>Base"/>
71+
72+
<ComplexType Name="value2<type>" BaseType="graph.<type>Base">
73+
<Property Name="<property-name>" Type="<property-type>"/>
74+
</ComplexType>
75+
```
76+
77+
## When to use this pattern
78+
79+
Use this pattern when supporting two or more collection states of the following, where at least one of the states is a subset variant:
80+
81+
- All targets
82+
- No targets
83+
- Subset of targets to be included
84+
- Subset of targets to be excluded
85+
86+
If you only ever need to support two states&mdash;All or None&mdash;without using any subsets, it would be better to use a Boolean to toggle on and off.
87+
88+
## Issues and considerations
89+
90+
Given that we are using an overarching subtype model, subtyping model limitations apply here as well; for more details, see the [subtyping documentation](./subtypes.md).
91+
92+
## Example
93+
94+
```http
95+
GET https://graph.microsoft.com/v1.0/identity/conditionalAccess/policies/
96+
```
97+
98+
_Note: Unrelated properties on entities are omitted for easier readability._
99+
100+
```json
101+
{
102+
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#conditionalAccessPolicy",
103+
"values": [
104+
{
105+
"id": "66d36273-fe4c-d478-dc22-e0179d856ce7",
106+
"conditions": {
107+
"users": {
108+
"includeGuestsOrExternalUsers": {
109+
"externalTenants": {
110+
"@odata.type":"microsoft.graph.conditionalAccessAllExternalTenants",
111+
"membershipKind": "all"
112+
}
113+
}
114+
}
115+
}
116+
},
117+
{
118+
"id": "99d212f4-d94e-cde1-8e3c-208d78238277",
119+
"conditions": {
120+
"users": {
121+
"includeGuestsOrExternalUsers": {
122+
"externalTenants": {
123+
"@odata.type":"microsoft.graph.conditionalAccessEnumeratedExternalTenants",
124+
"membershipKind": "enumerated",
125+
"members": ["bd005e2a-876d-4bf0-92a1-ae9ff4276d54"]
126+
}
127+
}
128+
}
129+
}
130+
}
131+
]
132+
}
133+
```
134+
135+
```http
136+
POST https://graph.microsoft.com/v1.0/identity/conditionalAccess/policies/
137+
```
138+
139+
_Note: Unrelated properties on entities are omitted for easier readability._
140+
141+
```json
142+
{
143+
"id": "66d36273-fe4c-d478-dc22-e0179d856ce7",
144+
"conditions": {
145+
"users": {
146+
"includeGuestsOrExternalUsers": {
147+
"externalTenants": {
148+
"@odata.type":"microsoft.graph.conditionalAccessAllExternalTenants"
149+
}
150+
}
151+
}
152+
}
153+
}
154+
```
155+
156+
or
157+
158+
```http
159+
POST https://graph.microsoft.com/v1.0/identity/conditionalAccess/policies/
160+
```
161+
162+
_Note: Unrelated properties on entities are omitted for easier readability._
163+
164+
```json
165+
{
166+
"id": "66d36273-fe4c-d478-dc22-e0179d856ce7",
167+
"conditions": {
168+
"users": {
169+
"includeGuestsOrExternalUsers": {
170+
"externalTenants": {
171+
"@odata.type":"microsoft.graph.conditionalAccessEnumeratedExternalTenants",
172+
"members": ["bd005e2a-876d-4bf0-92a1-ae9ff4276d54"]
173+
}
174+
}
175+
}
176+
}
177+
}
178+
```

0 commit comments

Comments
 (0)