The document outlines a series of events on API management and stewardship, highlighting a shift from oversight to providing value for developers. It emphasizes the importance of good API design practices, versioning strategies, and engaging teams early in the development process to avoid breaking changes and improve user experience. Additionally, it discusses tools and guidelines for maintaining APIs effectively while ensuring customer satisfaction.

1. Adrian Hall, Principal Program Manager

2. 2022 SERIES OF EVENTS
New York
JULY
(HYBRID)
Australia
SEPTEMBER
(HYBRID)
Singapore
APRIL
(VIRTUAL)
Helsinki & North
MARCH
(VIRTUAL)
Paris
DECEMBER
(HYBRID)
London
OCTOBER
(HYBRID)
Hong Kong
AUGUST
(VIRTUAL)
JUNE (VIRTUAL)
India
MAY
(VIRTUAL)
APRIL (VIRTUAL)
Dubai & Middle East
JUNE
(VIRTUAL)
Check out our API Conferences
www.apidays.global
Want to talk at one of our conferences?
apidays.typeform.com/to/ILJeAaV8

3. Discussion Topics
• Why so much focus on APIs?
• APIs in Azure
• Moving earlier in the process
• Providing value rather than oversight
• Development Culture and Tools
• API Guidelines
• Versions and Breaking Changes

4. 1 The 2017 State of the SaaS-Powered Workplace Report (bettercloud.com)
2 40+ Staggering SaaS Statistics to Know in 2021 - 99firms
3 iPaaS Market Size (Million Insights)
4The Dangers Of Cloud Sprawl (forbes.com)
%
“The best API-first companies give their users “superpowers” that they
wouldn’t have otherwise.”
Quoting an investor at Canvas Ventures

5. The Importance of API Stewardship
Growing an orchard, not inspecting the fruit
Stewardship: (n) the careful and responsible
management of something entrusted to one's
care <e.g. stewardship of natural resources>
• APIs are the contract between your service and
your customers/partners
• A good API can make dev work easy
• A bad one can send users to another service
• ”Good” means providing APIs that are
• Easy to use
• Fit to Purpose
• Consistent across your product
• Aligned with Industry Standards and
Conventions
• Scalable and Maintainable
API Stewardship is a practice that helps impart values of good API
design into your development process.

6. Bad APIs Happen Easier than Good Ones
Especially when delivering existing assets as APIs
• Easy ways to make a difficult API:
• Direct translation of data models
• Exposing interfaces that you didn’t
intentionally design
• Code Generation
• Building only one client implementation
• Evolving the product without evolving
how it is consumed
Swashbuckle
The “Telephone game” shows how easily
information can be corrupted via indirect
communication

7. APIs stick
around
much longer
than you
want
• Your customers take hard dependencies on your
interfaces
• Most API changes are not found until something
breaks
• Informing users of a change is rarely effective
• Designing to prevent change will save you effort
over time
• There are large downstream effects of changing APIs
• This is a terrible way to treat people you care about
• If it was not a good interface in the first place, you
will not enjoy supporting it
• But guess what?
• You are stuck with it now

8. REST APIs for the data plane of Azure Services
• Most Azure Services have a control plane
(manage and allocate resource to the
service) and a data plane (resources that are
managed by the service)
• We have governance in place for both –
control plane is much more prescriptive and
exposed through Azure Resource Manager
• For data plane, we have a lightweight
process called API Stewardship, run by a
board of experienced API practitioners

9. API Reviews
Too late in the process, high
friction, low effectiveness
• For years we had an API Review Board, which
looked at APIs as part of the checklist to go
to GA
• When Azure was small, this kind of
worked (but we didn’t have great
guidelines)
• As the number of new services grew,
awareness of guidelines and process
dropped
• A review just prior to GA is waaaay too late
• Teams found as many exceptions/ways
around the process as possible

10. Moving Earlier in the API Lifecycle
Engage at design time to have more impact
• We began to engage teams much earlier in the
API design process
• Included structured ways for teams to get API
feedback during previews
• Made a shift from “Review” to ”Stewardship”
• Investment was critical
• We dedicated staff (PM, Architect)
• Recruited more API Stewards
• Built content and tools to support this
mission
A paved road instead of a closed gate

11. Emphasize Providing Value Instead of Oversight
When teams saw value they kept coming back - and sent their peers
• Leaned-in to helping teams that were in the design stage vs those that
were already GA
• Focused on the developer use cases end to end
• Built content to help API designers make better choices
• Considerations for Service Design
• Designing and Versioning HTTP APIs
• Tackled problems with biggest customer impact first, then expanded
• Fault Tolerance (Idempotency - making operations repeatable without side-effects)
• Consistency across related services
• Easy APIs for Search/Query/Paging results
• Durability (Versioning and service evolution over time)

12. Building API Guidelines
Clarity is Kindness
• Having clear guidelines and examples helps a LOT
• Teams often want someone to tell them what to do
• Have a good reason for each choice you make
• Emphasize simplicity, durability, and empathy for the
client developer
• Share with your audience, build together, iterate
• Azure REST API Guidelines
• Microsoft REST API Best Practices
✅ DO
☑️ YOU SHOULD
✔️ YOU MAY
⚠️ YOU SHOULD
NOT
⛔ DO NOT

13. Some of the Key Guidelines
https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md
Uniform Resource Locators (URLs)
A Uniform Resource Locator (URL) is how developers access the resources of your service. Ultimately, URLs are how
developers form a cognitive model of your service's resources.
✅ DO use this URL pattern: https://<service>.<cloud>/<tenant>/<service-root>/<resource-collection>/<resource-id>/
Exactly Once Behavior = Client Retries & Service Idempotency
✅ DO ensure that all HTTP methods are idempotent.
☑️ YOU SHOULD use PUT or PATCH to create a resource as these HTTP methods are easy to implement, allow the customer to name their
own resource, and are idempotent.
✔️ YOU MAY use POST to create a resource but you MUST make it idempotent and, of course, the response MUST return the URL of the
created resource with a 201-Created. One way to make POST idempotent is to use the Repeatability-Request-ID & Repeatability-First-Sent
headers (See Repeatability of requests).
REpresentational State Transfer (REST)
REST is an architectural style with broad reach that emphasizes scalability, HTTP verbs as resource modifiers, independent deployment,
reduced latency via caching, and security.
✅ DO return status code 202-Accepted and follow the guidance in Long-Running Operations & Jobs when a PUT, PATCH, POST, or DELETE
method completes asynchronously.
✅ DO treat method names as case sensitive and should always be in uppercase
✅ DO return the state of the resource after a PUT, PATCH, POST, or GET operation with a 200-OK or 201-Created.
✅ DO return a 204-No Content without a resource/body for a DELETE operation (even if the URL identifies a resource that does not exist;
do not return 404-Not Found)
✅ DO support caching and optimistic concurrency by honoring the If-Match, If-None-Match, If-modified-since, and If-unmodified-since
request headers and by returning the ETag and last-modified response headers

14. API Discussions
Learn the use case, put yourself in the developer’s shoes, provide feedback
• We start by having the team explain their
domain and hero scenarios
• Sometimes we look at sample request/response
or client code
• Usually progresses to examining the OpenAPI
specification
• We talk through code flow, future evolution,
how different types will be used, etc.
• Swagger Editor is helpful for this

15. Infrastructure, Tools, and Process
Using the API specification can drive a lot of tooling
• We Use GitHub and Teams to track API specs, issues, agendas, outcomes
• From the GH repo, services take advantage automated tooling:
• Detecting API changes
• Bootstrapping SDKs with autorest (note that we then layer additional
code to craft the SDKs)
• Spectral Rulesets for checking aspects of the guidelines
• Using the Github PR process for commenting on specs
• Useful REST API tools:
• Spectral – OpenAPI Linter
• POSTman – API testing and development
• https://editor.swagger.io – easy OpenAPI spec viewer

16. API Gateways
Providing a consistent
infrastructure for
governance and
observability
API Gateways provide infra for cross-cutting concerns:
• Easy control points for security, identity, and release process
• Improve observability and telemetry
• Aggregation, routing, metering, and versioning

18. •Actual customer quotes
• "Too much breaking changes!"​
• "SDKs keep changing... Makes maintenance hard."​
• "It updates so often it is difficult to pin down software integration."​
• "Frequent API changes are annoying"​
• "Libraries often break considerably between versions. The chances of being able to
pick up last year's project and get it to run and publish first time are almost nil."​
•Two Requirements to avoid this pain
• Customer workloads must never break due to a service change
• Customers can adopt a version without requiring code changes
Empathize with your Customers

19. •Microsoft has 1 Azure SDK per language
•Each SDK has 1 client library (CL) per service
• CLs provide service object model (not flat), code completion, type-safety,
simple patterns (paging/LRO), credentials, retries, logging, telemetry,
distributed tracing, cancellation and much more
• Service changes impact all these CLs, tools (CLI/portal) & customers!
• A new CL must not require customer code changes
•This further constrains the changes a service can make!
Azure SDKs & Client Libraries

20. • Many languages can't load
v1.x & v2.x in the same process:
App can't run!
• For languages that can, there are still significant
problems (ex: size &
multiple singletons)
• Breaking changes invalidate the
entire ecosystem
• 3rd-party libraries, docs, samples,
blogs, videos, etc.
Why Breaking Changes are Forbidden
CL v1.0
CL v1.3
CL v2.0
App
Lib-A Lib-B
App
Lib-A
CL v1.3
Lib-B
CL v2.0

21. •Use api-version QP to signal new features
• https://api.contoso.com/users/Jeffrey?api-version=2021-07-27[-preview]
• Do not put version in path; path identifies resource regardless of version
•Customers opt-in to new features if/when they desire
• Happy customers may never opt-in to new features
• If they opt-in, they should only change existing code to leverage new features
•So, versioning an API is a misnomer
• You're really just adding new APIs & stating that the
newer version is preferred (but not mandatory)
• New versions run along side all previous versions
• NOTE: Resource state must be backward & forward compatible
• Changes to underlying resource structure span all API versions
• Ex: Changing a string's max length: new client sets long string/old client can't get/set it
Versioning Strategy – How we do it now

22. •Any contract change requires a new api-version
• Even additive changes or ambiguities arise
•Failure to follow this rule causes confusion
• Does api-version documentation include new features or not?
• Support can't know if an api-version honors new features or not
• Does a Client LibraryL for an api-version include the new features or not?
A Service's API is a Contract with Customers
Some Cloud
2019-01-24
Other Cloud
2019-01-24
w/new feature

23. 1. Engage early
2. Partner with producers
3. Add value, not oversight
4. Make clear API guidelines
5. Consider the SDK
Lessons Learned
6. Tooling helps
7. Use an API gateway
8. Centralize documentation
9. Version every change
10. No breaking changes

24. Thank you!