Skip to content

Commit 65dc630

Browse files
OlgaPodoOlgaPodo
committed
graph LRO
1 parent e973edb commit 65dc630

File tree

2 files changed

+189
-0
lines changed

2 files changed

+189
-0
lines changed

‎graph/patterns/change-notification.md

Whitespace-only changes.

‎graph/patterns/longRunningOperations.md

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Pattern Name
2+
3+
Microsoft Graph API Design Pattern
4+
5+
### *The Long Running Operations (LRO) Pattern provides the ability to model operations where processing a client request takes a long time, but the client isn't blocked and can do some other work until operation completion.*
6+
7+
## Problem
8+
9+
The API design requires modeling operations on resources which takes long time
10+
to complete so that API clients don't need to wait and can continue doing other
11+
work while waiting for the final operation result. The client should be able to
12+
monitor the progress of the operation and have an ability to cancel it if
13+
needed.The API needs to provide a mechanism to track the work
14+
being done in the background. The mechanism needs to be expressed in the same
15+
web style as other interactive APIs and support checking on the status and/or
16+
being notified asynchronously of the results.
17+
18+
## Solution
19+
20+
The solution is to model the API as a synchronous service which returns a
21+
resource representing the eventual completion or failure of a long-running
22+
operation.
23+
24+
There are two flavors of this solution:
25+
26+
1. The returned resource is the targeted resource and includes the status of
27+
the operation. This pattern is often called RELO (Resource based
28+
Long-running Operation).
29+
//image
30+
2. The returned resource is a new API resource called 'Stepwise Operation' and
31+
is created to track the status. This LRO solution is similar to the concept
32+
of Promises or Futures in other programming languages.
33+
//image
34+
35+
RELO pattern is the preferred pattern for long running operations and should be
36+
used wherever possible. The pattern avoids complexity and consistent resource
37+
presentation makes things simpler for our users and tooling chain.
38+
39+
In general Microsoft Graph APIs guidelines for LRO follow [Microsoft REST API
40+
Guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/graph/GuidelinesGraph.md).
41+
42+
A single deviation from the base guidelines is that Microsoft Graph API
43+
standards require using the following response headers:
44+
45+
- Content-Location header indicates location of a RELO resource.
46+
47+
- API response says the targeted resource is being created by returning 201 status code and the resource URI provided in the Content-Location header , but indicates the request is
48+
not completed by including "Provisioning" status.
49+
50+
- Location header indicates location of a new stepwise operation LRO resource.
51+
52+
- API response says the operation resource is being created at the URL
53+
provided in the Location header and indicates the request is
54+
not completed by including a 202 status code.
55+
56+
## When to Use this Pattern
57+
58+
59+
Any API call that is expected to take longer than 1 seconds in the 99th percentile, should use Long-running Operations pattern.
60+
61+
How to select which flavor of LRO pattern to use? API designer can follow these
62+
heuristics:
63+
64+
1. If a service can create a resource with a minimal latency and continue
65+
updating its status according to the well-defined and stable state
66+
transition model until completion then RELO model is the best choice.
67+
68+
2. Otherwise a service should follow the Stepwise Operation pattern.#
69+
70+
71+
## Issues and Considerations
72+
73+
1. One or more clients MUST be able to monitor and operate on the same resource
74+
at the same time.
75+
76+
2. The state of the system SHOULD be always discoverable and testable. Clients
77+
SHOULD be able to determine the system state even if the operation tracking
78+
resource is no longer active. Clients MAY issue a GET on some resource to
79+
determine the state of a long running operation
80+
81+
3. Long running operations SHOULD work for clients looking to "Fire and Forget"
82+
and for clients looking to actively monitor and act upon results.
83+
84+
4. Long running operations pattern may be supplemented by [Change Notification
85+
pattern](change-notification.md)
86+
87+
5. Cancellation does not explicitly mean rollback. On a per API defined case it
88+
may mean rollback, or compensation, or completion, or partial completion,
89+
etc. Following a canceled operation the API should return a consistent state which allows
90+
continued service.
91+
92+
6. A recommended minimum retention time for a stepwise operation is 24 hours.
93+
Operations SHOULD transition to "tombstone" for an additional period of time
94+
prior to being purged from the system.
95+
96+
7. Services that provides a new operation resource MUST support GET semantics on the operation.
97+
98+
99+
100+
## Examples
101+
102+
103+
### Creating a new resource using RELO
104+
105+
A client wants to provision a new database
106+
107+
```
108+
POST https://api.contoso.com/v1.0/databases/
109+
110+
{
111+
"id": "db1",
112+
}
113+
```
114+
115+
The API responds synchronously that the database has been created and indicates
116+
that provisioning operation is not fully completed by including the
117+
Operation-Location header and status property in the response payload.
118+
119+
```
120+
HTTP/1.1 201 Created
121+
Content-Location: https://api.contoso.com/v1.0/databases/db1
122+
123+
{
124+
"id": "db1",
125+
"Status": "Provisioning",
126+
[ … other fields for "database" …]
127+
}
128+
```
129+
130+
### Creating a new resource using Stepwise Operation:
131+
132+
```
133+
POST https://api.contoso.com/v1.0/databases/
134+
135+
{
136+
"id": "db1",
137+
}
138+
```
139+
140+
The API responds synchronously that the request has been accepted and includes
141+
the Location header with an operation resource for further polling .
142+
143+
```
144+
HTTP/1.1 202 Accepted
145+
146+
Location: https://api.contoso.com/v1.0/operations/123
147+
148+
```
149+
150+
### Polling on a Stepwise Operation:
151+
152+
```
153+
154+
GET https://api.contoso.com/v1.0/operations/123
155+
```
156+
157+
Server responds that results are still not ready and optionally provides a
158+
recommendation to wait 30 seconds.
159+
160+
```
161+
HTTP/1.1 200 OK
162+
Retry-After: 30
163+
164+
{
165+
"createdDateTime": "2015-06-19T12-01-03.4Z",
166+
"status": "running"
167+
}
168+
```
169+
Client waits the recommended 30 seconds and then invokes another request to get
170+
the results of the operation.
171+
172+
```
173+
GET https://api.contoso.com/v1.0/operations/123
174+
```
175+
176+
177+
Server responds with a "status:succeeded" operation that includes the resource
178+
location.
179+
180+
```
181+
HTTP/1.1 200 OK
182+
183+
{
184+
"createdDateTime": "2015-06-19T12-01-03.45Z",
185+
"lastActionDateTime": "2015-06-19T12-06-03.0024Z",
186+
"status": "succeeded",
187+
"resourceLocation": "https://api.contoso.com/v1.0/databases/db1"
188+
}
189+
```

0 commit comments

Comments
 (0)