apidays LIVE Singapore 2022: Digitising at scale with APIs
April 20 & 21, 2022
Lessons learned on the Azure API Stewardship Journey
Adrian Hall, Principal Product Manager at Microsoft
------------
Check out our conferences at https://www.apidays.global/
Do you want to sponsor or talk at one of our conferences?
https://apidays.typeform.com/to/ILJeAaV8
Learn more on APIscene, the global media made by the community for the community:
https://www.apiscene.io
Explore the API ecosystem with the API Landscape:
https://apilandscape.apiscene.io/
Deep dive into the API industry with our reports:
https://www.apidays.global/industry-reports/
Subscribe to our global newsletter:
https://apidays.typeform.com/to/i1MPEW
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
17.
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
Even if your use case is for internal consumers, it is important to think of yourself as a SaaS platform provider.
Think about your API as the product you are offering.
APIs build ecosystems—if they:
Expose valuable capability
Are stable and durable
Are easy to use
Embedded in business process equates to a high switching cost.
When building software components that will be used by developers to build other software, providing APIs that are easy to use, fit to purpose, scalable, maintainable, and consistent across your product can make the difference between success and failure for your software. The API you ship can have a dramatic long-term effect on the health of your software product.
What is the difference between a *good* API and a poor one?
How can you focus on designing APIs that are developer-focused, easy-to-use, scalable, and powerful enough to fully expose the features of your service?
When is it OK to change an API that is in use? How should you offer and govern API lifecycle for backcompat?
API Stewardship is a practice that helps impart values of good API design into your development process.
Some examples of standards include those at the protocol layer (REST+JSON+headers, etags, etc) and the data layer (data models, dates and times, telephone numbers, geojson etc
For KPMG, the risk is developers in member firms go off and build their own apps and build data siloes that don't come back to the master system.
Sometimes this is called drift.
Often we write software with a fairly narrow set of use cases and a narrow purpose. With iteration and time the use cases expand, people use the software in ways we didn’t realize they would, or the compromises made when prototyping get built-in as the code grows. Abstractions that look great with one implementation suddenly look awkward or leaky when it is time to build another. For a succinct and impactful look at these problems, read Joshua Bloch’s presentation on API Design.
The API is a contract between the service and the customer.
Should be well understood and well documented. Too often APIs grow organically over time, are built from implementation code using generators, or are derived from the code written to enable test automation. These methods result in APIs that often make life very difficult for client developers.
Once the product or service is in use, or an internal class is suddenly consumed by multiple modules, you now have “legacy” code that depends upon your API design and if you change it you have to figure out how to do backcompat or update all of those dependencies or more likely both. Avoiding unnecessary API changes and backcompat hassles by being deliberate and thoughtful about API design from the beginning will yield significant returns over the lifetime of your projects.
Downstream effect: client libraries, now used in other applications, the implication of change multiplies over time as APIs are used….
Tooling to detect changes, esp. breaking changes.
Examples with Azure CLI
BE OPEN & INCLUSIVE
Win the “hearts & minds” through transparency and bringing value.
BE thoughtful about where you put the gates.
The Stewardship board at MS is a voluntary effort. We work hard to get buy in from our “customers” (Azure Service teams) by brining value to the table.
Intentionally, not a gate or a “review” board. The service team is responsible for adhering to Azure governing policies, e.g. Breaking Changes.
We are inclusive—anyone is welcome to participate. Currently members from DevDiv, Azure Services, CTO Office, and CSE
Going back to the value discussion…
APIs are not just “code” but ALL the things around it, e.g. infrastructure, release process, documentation, etc.
Where can you bring VALUE?
don't support http://SemVer.org
Ex: C, C++, C#, Java, Android, iOS
Adding new properties requires a change in api-version for 3 reasons:
Some language (de)serializers throw if a new property comes across the wire that the client library has no field for in a structure/class.
And old client discards the new property when it receives it from the service and doesn’t send it back to the service resulting in data loss/corruption.
Perpetual preview & breaking valued preview customers while helping you polishing your service