microsoft confidential€¦ · microsoft confidential ance include representatives from different...
TRANSCRIPT
![Page 1: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/1.jpg)
Microsoft Confidential
![Page 2: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/2.jpg)
How we design (and build) Microsoft Graph
Mark Stafford
Program Manager, Microsoft Graph
Microsoft Confidential
![Page 3: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/3.jpg)
Agenda
Microsoft Confidential
![Page 4: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/4.jpg)
Scale
Microsoft Confidential
![Page 5: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/5.jpg)
500%resource growth (2 years)
5B+daily requests
100xprojected request growth (2 years)
Graph size
Microsoft Confidential
![Page 6: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/6.jpg)
Architecture
Microsoft Confidential
![Page 7: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/7.jpg)
Graph architecture (glossary)
graph.microsoft.com
Directory Exchange Intune Teams
Microsoft Confidential
![Page 8: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/8.jpg)
graph.microsoft.com
Directory Exchange Teams …
Graph architecture (ultra-simplified)
Microsoft Confidential
![Page 9: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/9.jpg)
graph.microsoft.com
Directory Exchange …
graph.msft.cn
Directory Exchange …
Graph architecture (sovereign clouds)
Microsoft Confidential
![Page 10: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/10.jpg)
Microsoft Confidential
graph.microsoft.com
Teams
chat
Teams
calling
Teams
channels
Graph architecture (microservices)
![Page 11: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/11.jpg)
graph.microsoft.com
SharePointA SharePointB SharePointC
Graph architecture (user discovery)
Microsoft Confidential
![Page 12: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/12.jpg)
Consistency
Microsoft Confidential
![Page 13: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/13.jpg)
Customers
perceive
Graph as a
single API
Different
Products
Different API
Teams
Different
Philosophies
Different
Velocities
Consistency is the promiseC
ON
SIS
TEN
CY
Microsoft Confidential
![Page 14: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/14.jpg)
Graph Guidelines
Microsoft REST API Guidelines
OData
HTTP/JSON
Microsoft’s foundation for API guidance
Microsoft Confidential
CO
NS
IST
EN
CY
![Page 15: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/15.jpg)
Microsoft Confidential
CO
NS
IST
EN
CY
HTTP/JSON (httpwg.org, json.org)
![Page 16: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/16.jpg)
Microsoft Confidential
CO
NS
IST
EN
CY
OData (odata.org), the REST standard
![Page 17: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/17.jpg)
Microsoft Confidential
CO
NS
IST
EN
CY
Microsoft REST API Guidelines (aka.ms/apiguide)
![Page 18: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/18.jpg)
Microsoft Confidential
CO
NS
IST
EN
CY
Graph-specific guidelines (internal)
![Page 19: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/19.jpg)
Microsoft Confidential
Guidance
![Page 20: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/20.jpg)
Microsoft Confidential
GU
IDA
NC
EConsistency requires TONS of guidance
▅ Fundamentals – HTTP, JSON,
REST
▅ Headers – required, anti-
proliferation
▅ Principles – symmetry, burden
owner
▅ Naming – casing, conventions
▅ Query – filter, order, top
▅ Pagination
▅ Errors – payload, 429 vs 503
▅ Patterns
• Modeling – singleton, evolvable
enums
• API – long-running operations,
deltas, webhooks
▅ Throttling – leaky token
bucket
▅ Graph maturity model
![Page 21: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/21.jpg)
Microsoft Confidential
GU
IDA
NC
E
▅ Must be thoroughly documented
▅ Must be approachable for new people
▅ Must have detail for experienced people
▅ Must accommodate different learning styles
▅ Must continue to evolve
▅ Must be accompanied by libraries
▅ Microsoft has thousands of pages of guidance, and many .NET
libraries
Guidance is hard
![Page 22: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/22.jpg)
Microsoft Confidential
GU
IDA
NC
E
▅ Include representatives from different teams and roles
▅ Meet weekly, record meetings
▅ Discuss challenges
▅ Articulate the problem as a customer scenario
▅ Be open-minded when discussing solutions
▅ Make decisions on principles, not votes
▅ Don’t rush decisions
▅ Write-down the decisions and evolve the guidance
▅ Microsoft has an API council that meets for an hour a week; we record every
meeting for later reference
Guidance is formed by a council
![Page 23: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/23.jpg)
Microsoft Confidential
GU
IDA
NC
E
▅ Example: erasing silos
• Can workloads use custom headers?
• When do we design generically vs. specifically, e.g. “select all”
▅ Example: versioning
• What requires a version bump?
• Would we bump a major version if there is no customer value?
• Should new apps use multiple API versions or the latest version?
• When can we really “turn off” an old version?
▅ Microsoft invests most of our API council time in philosophy
Guidance is formed on philosophy
![Page 24: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/24.jpg)
Microsoft Confidential
GU
IDA
NC
E
▅ We cannot stagnate• SOAP is old and has many issues• Influential voices are questioning REST
▅ We must be careful how we evolve• Protect client apps• Make affordances for existing workloads• Ask, is this change 10x better?
▅ Consider what the gateway can do• Cleanup & transformation• Protocol translation
▅ Microsoft is considering the impact of gRPC, GraphQL, and “post-REST”
Guidance must evolve
![Page 25: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/25.jpg)
Microsoft Confidential
API review
![Page 26: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/26.jpg)
Microsoft Confidential
AP
I REV
IEW
▅ How to scale?
▅ How to get consistent results with many reviewers?
▅ The right focus for API review
▅ Enforcing that changes are made
▅ Ensuring that published APIs conform to review
▅ Passing API review the first time
API review has many challenges
![Page 27: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/27.jpg)
Microsoft Confidential
AP
I REV
IEW
▅ Plan for multiple API review teams
▅ Plan for API review teams to change over time
▅ This means API reviewers also need guidance
▅ Solicit input from API reviewers
▅ Meet regularly
▅ Microsoft has API review teams for Identity, Office, Windows, and more
▅ Microsoft ensure that the API council is formed primarily of API reviewers
Scaling API review
![Page 28: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/28.jpg)
Microsoft Confidential
AP
I REV
IEW
▅ It’s easy to get lost in details
▅ “The devil is in the details”
▅ PATCH vs. PUT is important, but not a topic for API review
▅ Tooling is a huge help in focusing API review
▅ Linters help teams get the API right before review
▅ Microsoft is still working through this challenge
▅ Microsoft builds API linters to handle the details
▅ Microsoft focuses API review on user scenarios and intuitiveness of the
model
Consistent results & right focus
![Page 29: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/29.jpg)
Microsoft Confidential
AP
I REV
IEW
▅ Lots of feedback is given in each API review
▅ Feedback may require or recommend changes, or just be “for consideration”
▅ Feedback must be actioned
▅ The final result must be clear
▅ Microsoft treats API review like code review
▅ Microsoft uses pull requests to make reviews traceable – PRs handle action on
feedback
▅ Microsoft uses CI to prescreen reviews with linters
▅ Microsoft uses accepted PRs as “contracts”
Enforcing that changes are made
![Page 30: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/30.jpg)
Microsoft Confidential
AP
I REV
IEW
▅ There’s typically a gap between review and publishing
▅ Ensure that what gets published = what was reviewed
▅ Automate this process!
▅ Microsoft uses additional CI/CD to compare publish artifacts
with review artifacts
▅ Microsoft WILL eventually pivot around the review artifact,
making inconsistent publish impossible
What gets published = what was reviewed
![Page 31: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/31.jpg)
Microsoft Confidential
Onboarding
![Page 32: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/32.jpg)
Microsoft Confidential
Design Review Develop Document Publish Promote
API onboarding stages
![Page 33: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/33.jpg)
Microsoft Confidential
▅ Minimize number and type of artifacts required• Review artifact• Publish artifact• Changelog• Documentation
▅ Not all APIs are “public”
▅ Multiple clouds and versioning are challenging
▅ Microsoft is working toward 1-artifact publishes
▅ Microsoft uses exposure control to support private APIs
▅ Microsoft has not solved the “what’s where?” challenge
Onboarding challenges
![Page 34: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/34.jpg)
Microsoft Confidential
▅ Automate everything other than human review
▅ Provisioning of “test” endpoint
▅ Publish to beta, v1.0, sovereign clouds• Sovereign clouds typically require escorts
▅ Generate changelog and public docs
▅ Microsoft wants the review artifact to be the only artifact
▅ Microsoft has automated the provisioning of test endpoints and
publishing to sovereign clouds
▅ Microsoft is working on automating promotion to beta, v1.0
Automate onboarding
![Page 35: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/35.jpg)
Microsoft Confidential
Open issues
![Page 36: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/36.jpg)
Microsoft Confidential
▅ Should the gateway help with cross-cutting functionality such
as throttling and query?
▅ Should the gateway handle protocol translation?
• On the external side, e.g. GraphQL head
• On the internal side, to allow more flexibility for onboarding
▅ Who handles telemetry?
▅ Microsoft currently adds minimal functionality to the gateway
▅ Microsoft’s gateway provides basic telemetry
Gateway vs. workload responsibilities
![Page 37: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/37.jpg)
Microsoft Confidential
▅ 2019: Hundreds of billions of API calls per day
▅ 8 milliseconds overhead
▅ Some workloads have specialized routing
• Example: Outlook routes calls by user
• Every additional hop introduces latency
▅ When should workloads receive calls directly?
▅ Microsoft will allow certain workloads to receive calls directly;
restricted to first-party apps (more complex)
Operating at extreme scale
![Page 38: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/38.jpg)
Microsoft Confidential
![Page 39: Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem](https://reader035.vdocuments.site/reader035/viewer/2022062508/60159e0c0fc23e6534724744/html5/thumbnails/39.jpg)
Microsoft Confidential