microsoft confidential€¦ · microsoft confidential ance include representatives from different...
TRANSCRIPT
Microsoft Confidential
How we design (and build) Microsoft Graph
Mark Stafford
Program Manager, Microsoft Graph
Microsoft Confidential
Agenda
Microsoft Confidential
Scale
Microsoft Confidential
500%resource growth (2 years)
5B+daily requests
100xprojected request growth (2 years)
Graph size
Microsoft Confidential
Architecture
Microsoft Confidential
Graph architecture (glossary)
graph.microsoft.com
Directory Exchange Intune Teams
Microsoft Confidential
graph.microsoft.com
Directory Exchange Teams …
Graph architecture (ultra-simplified)
Microsoft Confidential
graph.microsoft.com
Directory Exchange …
graph.msft.cn
Directory Exchange …
Graph architecture (sovereign clouds)
Microsoft Confidential
Microsoft Confidential
graph.microsoft.com
Teams
chat
Teams
calling
Teams
channels
Graph architecture (microservices)
graph.microsoft.com
SharePointA SharePointB SharePointC
Graph architecture (user discovery)
Microsoft Confidential
Consistency
Microsoft Confidential
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
Graph Guidelines
Microsoft REST API Guidelines
OData
HTTP/JSON
Microsoft’s foundation for API guidance
Microsoft Confidential
CO
NS
IST
EN
CY
Microsoft Confidential
CO
NS
IST
EN
CY
HTTP/JSON (httpwg.org, json.org)
Microsoft Confidential
CO
NS
IST
EN
CY
OData (odata.org), the REST standard
Microsoft Confidential
CO
NS
IST
EN
CY
Microsoft REST API Guidelines (aka.ms/apiguide)
Microsoft Confidential
CO
NS
IST
EN
CY
Graph-specific guidelines (internal)
Microsoft Confidential
Guidance
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
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
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
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
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
Microsoft Confidential
API review
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
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
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
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
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
Microsoft Confidential
Onboarding
Microsoft Confidential
Design Review Develop Document Publish Promote
API onboarding stages
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
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
Microsoft Confidential
Open issues
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
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
Microsoft Confidential
Microsoft Confidential