APIs that Age Well

Almost all Web APIs evolve over time. New features are added, new clients start consuming them, the API design changes, and breaking changes are introduced. While natural, it can be frustrating for API developers and clients alike to deal with unclear design or unexpected breaking changes.

This workshop, built for .NET API developers, explores how OpenAPI provides the foundation for documenting, governing, and evolving APIs safely over time:

- How do we communicate new features and the way we would like them to be used?
- How do we deal with breaking changes, informing our clients of them, and detecting unintended ones?
- And how do we make it easy for clients to use our API, given that they might use all kinds of programming languages?
- Finally, how do we ensure that the API style matches the intent and standards of other teams, so we don't waste time on unnecessary discussions and rework?

Putting all of this together, we end up with an API that ages well, one that is easy to use, easy to maintain, and easy to evolve.

We'll be using ASP.NET Core and Azure API Center, a registry for cataloging and governing APIs, to demonstrate these concepts, but these principles can be applied to any technology stack, thanks to the underlying specification that will power all of these concepts: OpenAPI. We'll be using open tooling and technologies like Swagger UI, Scalar, API Versioning, Spectral and oasdiff.

We'll start with a simple API and add different features to it, demonstrating the problems that arise and then solving them. By the end of the workshop, you'll have built an API that can survive years of change, featuring versioning, high-quality OpenAPI documentation, automated linting, breaking change detection, generated client SDKs, and cloud-based API governance.

Prerequisites:

- Your own laptop.
- Internet access.
- A GitHub account to host your repository and run GitHub Actions.
- You can also use GitLab or Azure DevOps if you prefer, but the workshop will be using GitHub.
- A Code Editor.
- Visual Studio Code is recommended, but you can use any editor you like.
- Docker or the latest .NET SDK with permission to install tools like Spectral and Oasdiff.
- (Optional) A (free) Azure account (or an existing one) to use Azure API Center.
- If you can't use Azure, you can still follow along with the workshop and use local tools to achieve the same results.