Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem

Microsoft Confidential

How we design (and build) Microsoft Graph

Mark Stafford

Program Manager, Microsoft Graph


Agenda


Scale


500%resource growth (2 years)

5B+daily requests

100xprojected request growth (2 years)

Graph size


Architecture


Graph architecture (glossary)

graph.microsoft.com

Directory Exchange Intune Teams


graph.microsoft.com

Directory Exchange Teams …

Graph architecture (ultra-simplified)


graph.microsoft.com

Directory Exchange …

graph.msft.cn

Directory Exchange …

Graph architecture (sovereign clouds)



graph.microsoft.com

Teams

chat

Teams

calling

Teams

channels

Graph architecture (microservices)

graph.microsoft.com

SharePointA SharePointB SharePointC

Graph architecture (user discovery)


Consistency


Customers

perceive

Graph as a

single API

Different

Products

Different API

Teams

Different

Philosophies

Different

Velocities

Consistency is the promiseC

ON

SIS

TEN

CY


Graph Guidelines

Microsoft REST API Guidelines

OData

HTTP/JSON

Microsoft’s foundation for API guidance


CO

NS

IST

EN

CY


CO

NS

IST

EN

CY

HTTP/JSON (httpwg.org, json.org)


CO

NS

IST

EN

CY

OData (odata.org), the REST standard


CO

NS

IST

EN

CY

Microsoft REST API Guidelines (aka.ms/apiguide)


CO

NS

IST

EN

CY

Graph-specific guidelines (internal)


Guidance


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


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


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


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


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


API review


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


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


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


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


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


Onboarding


Design Review Develop Document Publish Promote

API onboarding stages


▅ 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


▅ 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


Open issues


▅ 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


▅ 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



Documents

Microsoft Confidential€¦ · Microsoft Confidential ANCE Include representatives from different teams and roles Meet weekly, record meetings Discuss challenges Articulate the problem