Skip to content

Commit 73aca77

Browse files
OlgaPodoOlgaPodo
committed
added examples
1 parent ff079f6 commit 73aca77

File tree

1 file changed

+58
-24
lines changed

1 file changed

+58
-24
lines changed

‎graph/patterns/operations.md

Lines changed: 58 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,11 @@ Microsoft Graph API Design Pattern
66

77
## Problem
88

9-
Sometimes when modeling a complex business domain, API designers need to model a business operation that effects one or multiple resources and has additional semantic meaning that cannot be expressed by HTTP methods. Modeling the operation via HTTP methods on each individual resource might be either inefficient or expose internal implementation details. In addition, the operation might produce observable side effects.
9+
Sometimes when modeling a complex business domain, API designers need to model a business operation that effects one or multiple resources and has additional semantic meaning that cannot be expressed by HTTP methods. Modeling the operation via HTTP methods on each individual resource might be either inefficient or expose internal implementation details.
1010

1111
## Solution
1212

13-
To address these use cases, API designers can use operational resources such as functions or actions.
14-
If the operation doesn't have any side effects and MUST return a single instance of a type or a collection of instances, then the designer MUST use OData functions; otherwise, the designer can model the operation as an action.
13+
To address these use cases, API designers can use operational resources such as functions or actions. If the operation doesn't have any side effects and MUST return a single instance of a type or a collection of instances, then the designer SHOULD use OData functions; otherwise, the designer can model the operation as an action.
1514

1615
## When to use this pattern
1716

@@ -21,15 +20,14 @@ The operation pattern might be justified when a modeling operation represents on
2120

2221
- a change of a resource (i.e., increment the value of a property) rather than a state (i.e., the final value of the property)
2322
- complex processing logic that shouldn't be exposed to the client
24-
- operation parameters might convey a restricted set of option (i.e., a report that can has to specify a date range)
23+
- operation parameters might convey a restricted set of option (i.e., a report that has to specify a date range)
2524
- the operation leverage some service-side data not exposed to (or easily retrieved in context by) the user.
2625

2726
You can consider related patterns such as [long running operations](./long-running-operations.md) and [change tracking](./change-tracking.md).
2827

2928
## Issues and considerations
3029

31-
- Microsoft Graph does NOT support unbound actions or functions. Bound actions and functions are invoked on resources matching the type of the binding parameter. The binding parameter can be of any type, and parameter value MAY be Nullable.
32-
For Microsoft Graph, actions and functions must have the `isBound="true"` attribute. The first parameter is the binding parameter.
30+
- Microsoft Graph does NOT support unbound actions or functions. Bound actions and functions are invoked on resources matching the type of the binding parameter. The binding parameter can be of any type, and parameter value MAY be Nullable. For Microsoft Graph, actions and functions must have the `isBound="true"` attribute. The first parameter is the binding parameter.
3331

3432
- Both actions and functions support overloading, meaning a schema might contain multiple actions or functions with the same name. The overload rules as per the OData [standard](http://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/odata-csdl-xml-v4.01.html#sec_FunctionOverloads) apply when adding parameters to actions and functions.
3533

@@ -46,29 +44,65 @@ For Microsoft Graph, actions and functions must have the `isBound="true"` attrib
4644

4745
- The addition of a new mandatory not-nullable parameter to an existing action or function is a breaking change and is not allowed without proper versioning that is in accordance with our [deprecation guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/graph/deprecation.md).
4846

49-
## Example
47+
## Examples
48+
49+
### A user wants to forward email
5050

5151
```
52-
<Action Name="createUploadSession" IsBound="true" ags:EnabledForPassthrough="true" ags:OwnerService="Microsoft.Exchange">
53-
<Parameter Name="bindingParameter" Type="Collection(graph.attachment)" />
54-
<Parameter Name="AttachmentItem" Type="graph.attachmentItem" Nullable="false" />
55-
<ReturnType Type="graph.uploadSession" />
56-
</Action>
52+
POST https://graph.microsoft.com/v1.0/me/messages/AQMkADNkMmMxYzIwLWJkOTItNDczZC1hNmYyLWUwZjk2ZTljMDQyNQBGAAAD1dY5iRo4x0_pEqop6hOrQAcAeGCrbYV1-kiG-z9Rv6yHMgAAAgEJAAAAeGCrbYV1-kiG-z9Rv6yHMgABRxeUKgAAAA==/forward
53+
54+
{
55+
"comment": "FYI",
56+
"toRecipients": [
57+
{
58+
"emailAddress": {
59+
"address": "[email protected]",
60+
"name": "Alex Darrow"
61+
}
62+
}
63+
]
64+
}
65+
```
66+
Response:
67+
```
68+
HTTP/1.1 202 Accepted
69+
70+
"cache-control": "private",
71+
"client-request-id": "ca2d0416-a2c1-05af-df60-0921547a86e9",
72+
"content-length": "0",
73+
"request-id": "8b53016f-cc2b-4d9f-9818-bd6f0a5e3cd0"
74+
```
5775

58-
<Action Name="deprovision" IsBound="true" ags:OwnerService="Microsoft.Intune.Devices">
59-
<Parameter Name="bindingParameter" Type="graph.managedDevice" />
60-
<Parameter Name="deprovisionReason" Type="Edm.String" Nullable="false" Unicode="false" />
76+
`forward` operation is modeled as an asynchronous action bound to the Graph `event` entity type because the operation represents a complex business logic processed on the server side.
77+
```
78+
<Action Name="forward" IsBound="true" >
79+
<Parameter Name="bindingParameter" Type="graph.event" />
80+
<Parameter Name="ToRecipients" Type="Collection(graph.recipient)" />
81+
<Parameter Name="Comment" Type="Edm.String" Unicode="false" />
6182
</Action>
83+
```
6284

63-
<Function Name="additionalAccess" IsBound="true" ags:OwnerService="Microsoft.IGAELM">
64-
<Parameter Name="bindingParameter" Type="Collection(graph.accessPackageAssignment)" />
65-
<ReturnType Type="Collection(graph.accessPackageAssignment)" />
66-
</Function>
85+
### A user wants to see recent application activities
6786

68-
<Function Name="compare" IsBound="true" ags:OwnerService="Microsoft.Intune.DeviceIntent">
69-
<Parameter Name="bindingParameter" Type="graph.deviceManagementIntent" />
70-
<Parameter Name="templateId" Type="Edm.String" Unicode="false" />
71-
<ReturnType Type="Collection(graph.deviceManagementSettingComparison)" />
72-
</Function>
87+
```
88+
GET https://graph.microsoft.com/v1.0/me/activities/recent
89+
```
90+
91+
Response:
92+
93+
```
94+
HTTP/1.1 200 OK
7395
96+
{
97+
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(userActivity)",
98+
"value": []
99+
}
100+
```
101+
`recent` function will query the most recent historyItems and then pull related activities therefore the operation represents a complex business logic processed on the server side. This operation doesn't change any server data and is a good fit for a function. The function is bound to the collection of `userActivity` entity type.
102+
103+
```
104+
<Function Name="recent" EntitySetPath="activities" IsBound="true">
105+
<Parameter Name="bindingParameter" Type="Collection(graph.userActivity)" />
106+
<ReturnType Type="Collection(graph.userActivity)" />
107+
</Function>
74108
```

0 commit comments

Comments
 (0)