A presentation given by Mandy Whaley, Partner Director of Product, Azure Developer Tools at Microsoft, at our 2024 Austin API Summit, March 12-13. Session Description: TypeSpec is a new API description language developed and used by Microsoft to deliver APIs at a massive scale. Learn how Microsoft uses TypeSpec to deliver high quality services to millions of customers and across tens of thousands of API endpoints. We will show how to use this new language and the related IDE tooling to encapsulate common API patterns into reusable components, up-level API descriptions with business-specific metadata and behaviors, connect API guidelines to development time activities, maintain API consistency, and generate custom assets, all while interoperating with the OpenAPI ecosystem.

1. APIs at Scale with
TypeSpec
Mandy Whaley
Partner Director, Azure SDK & Dev Tools

2. I lead the Azure Developer Tools team.
We build the Azure SDK, Azure Dev Tools for Visual Studio and VS Code, and
work with teams across Microsoft on API design and developer experience.
I live in Austin, and I love to knit and crochet and have 3 hilarious dogs.
Twitter: @AzureSDK @MSAzureDev
LinkedIn: www.linkedin.com/in/mandywhaley
/me

3. Mission of Azure SDK team
Create
and experiences for developers to

4. • Many APIs, built by many teams​​
• 100s of libraries: Storage, Key Vault, Event Grid + more​
• Idiomatic libraries​ (Python, JavaScript, .NET, Java, Go)
• REST API Guidelines & API Stewardship
Microsoft Azure SDK

5. Understanding the scale of Azure
Building great developer experience across hundreds of teams and services isn’t easy.
Hundreds of teams and services
across the globe.
Hundreds of client libraries across
multiple languages.
Thousands of service operations,
and tens of thousands of API
shapes.
Teams and services Client libraries Service operations

6. Azure SDK Design Guidelines
An open-source suite of SDKs (Python, JavaScript, .NET, Java, Go) that share common design
guidelines, a centralized engineering system, and consistent language and OS support.
Productivity
Developer
productivity is the
primary objective.
Consistent
Similar experience
within and across
services and
languages.
Approachable
Quickly get
started, learn, and
build.
Idiomatic
Natural language
experience and
standard package
managers.
Diagnosable
Easily observe
applications.
Dependable
High quality, avoid
breaking changes.

7. Why design “API first?”
Deriving APIs from existing code can lead to inconsistent customer-facing software that’s hard to maintain and version
“I don’t understand how this API
works at all.”
“It’s easier to write code first and
then derive the API layer, but then
my code tends to be all over the
place.”
“I wish our services didn’t have all
these different ways of exposing
similar concepts through the APIs.”
“I wish I’d thought of that
requirement in version 1 before
locking us into that API shape.”
Clients Developers Customer support Service lifetime
Code designed with the client’s
ease of use in mind leads to
happier customers.
Code developed against
intentionally-designed APIs is
more modular and focused,
leading to fewer bugs.
Services which conform to a well-
understood API standard are easier
to assess and support.
APIs designed with future growth
in mind are easier to maintain and
version.

8. • OpenAPI can be hard to write, review, and maintain
• New teams struggle with following API guidelines
• Supporting multiple versions of APIs
• Multiple Protocols - The same data shapes are used across different
protocols, for example REST and gRPC
• Scaling our SDK engineering team and API Architects to support Azure
growth
Challenges

9. We need a way to…
Codify our API guidelines into reusable components.
Easily describe operations and their associated data shapes.
Improve the developer experience of designing APIs by providing productive tooling that
highlights problems at development time.
Support a wide range of protocols and serialization formats.
Drive the generation of high-quality assets across the entire service delivery pipeline (services,
clients, docs, CLIs, and other API specification formats).
1
2
3
4
5

10. Microsoft Developer Division
TypeSpec
Lightweight language for
describing and designing APIs
Easy integration with your
OpenAPI toolchain
Turn your API guidelines
into reusable code
typespec.io

11. Microsoft Developer Division
Easily describe API shapes and create OpenAPI specifications
TypeSpec
is concise & human readable
Committed to interoperability
with OpenAPI
Integrates with your toolchain

12. Microsoft Developer Division
Turn your API guidelines into reusable code
TypeScript libraries can help you turn
your API guidelines and patterns into
code that is reusable and easy to adopt.
TypeSpec libraries are packages that
contain TypeSpec
• types
• decorators
• emitters
• linters and other bits of reusable code.
Generic example Code snippets here

13. Microsoft Developer Division
Full language support in VS Code and Visual Studio
The TypeSpec VS Code extension
provides features for efficient and
error-free coding:
• Autocompletion
• Syntax highlighting
• Build error identification
• Symbol renaming
• Document formatting

14. Lessons Learned
& Feedback

15. Microsoft Developer Division
Simple: Easier to understand and easy to author. Scales the
API expertise in your org to everyone
Scalable: The extensibility of TypeSpec supports teams
working in parallel and independently to define libraries,
types and emitters.
Intuitive: Enables non-engineers to understand, review, and
participate in API design.
Collaborative: Facilitates cross-functional team
involvement in the API design phase
Tooling: Easy to install, and get started, Integration with
VS code out of the box.
What users value about TypeSpec

16. Microsoft Developer Division
Faster: TypeSpec is faster for us to review for
API correctness
Reusable Libraries: Teams automatically
start on the right path and follow our API
Guidelines when they use TypeSpec libraries
Encourages Design-First approach: By
making it easier to author API specs at design
time, we are able to engage with teams early
and get them thinking about the end user
experience for their APIs
Observations from our API architects
TypeSpec has improved our API review
process
API Lifecycle: Existing services and new
services are able to adopt API guidelines
at different speeds
TypeSpec needs to be flexible to support
teams at any point in their journey
Flexibility is key
Consistency: Resuable building blocks
bring more consistency to our APIs
Focus: Because we are using consistent
building blocks, we can focus on higher
level API experience topics vs. spending so
much time on error codes, etc.
Client Libraries: We are using the extra
metadata that can be expressed in
TypeSpec as an input to inform our client
code generation on ways to provide
higher level APIs
Improved DevEx

17. Microsoft Developer Division
ARM APIs have extensive API guidelines
ARM APIs follow strict conventions
Can be represented with thousands of lines
of OpenAPI
Internal use case: TypeSpec for Azure Resource Provider (ARM) services
High level API components drive the generation of thousands of lines of OpenAPI
TypeSpec encapsulates these guidelines and
API patterns into reusable components
Service owners just use the component!

18. Microsoft Developer Division
Getting started with TypeSpec – TypeSpec.io
https://typespec.io/playground

19. Microsoft Developer Division
• We welcome contributions!
• Questions? Ideas?
• We would love to hear
from you
• Reach out in our GitHub
Discussions
TypeSpec is open source
github.com/microsoft/typespec
typespec.io

20. Typespec.io
github.com/microsoft/typespec
Twitter: @AzureSDK @MSAzureDev
LinkedIn: www.linkedin.com/in/mandywhaley