Something we focus on, when building a great Azure developer experience, are the common patterns that many Azure services implement. More often than not, one that we encounter is long-running operations, or “LROs” for short. Because we keep encountering this pattern, how we think about LROs has evolved.

Towards the end of last year, we took the first step to refine how teams should describe and model LROs. This updated guidance is captured in two main documents:

• The Azure REST API guidelines, which is the prescriptive approach to implementation.
• The considerations for service design, which provides the rationale behind our guidance.

A major objective for the API Stewardship Board is to strive for consistency across all of Azure. Even after our updates, LROs remained an area where it seemed we were always finding edge cases or discovering that each team took a slightly different approach. We recognized a need to tackle LROs again.

Earlier this year, we studied where teams were struggling with our guidance, reviewed the edge cases, and studied where we struggle to implement LROs elegantly in the Azure SDKs. The result is another iteration of guidance for LROs. Here are some of the areas that were improved:

• We simplified our guidance by eliminating the “resource-based long-running operation” (RELO) pattern. Allowing two different LRO patterns increased complexity without adding real value. Furthermore, we learned that RELO can be unreliable if not implemented correctly.
• We added an operation-id header (optional) that can be used to make LROs idempotent. A retried request to initiate an LRO doesn’t create a new status monitor resource if the operation-id header is included in the request.
• We required that the operation status endpoints be documented and defined a clear linkage from operations that initiate LROs to the corresponding operations to obtain the status and results.

We think our updated guidance is another step forward in driving clarity and consistency around Azure LROs. However, we’d love to know what you think. There’s a pull request in our repo in which you’re welcome to review the update to the guidelines and the considerations document and provide feedback.