Q&A
Versioning and Documenting ASP.NET Core Services
Building an API with ASP.NET Core is only half the job. If your API is going to live more than one release cycle, you're going to need to version it. If you have other people building clients for it, you're going to need to document it.
"Versioning enables a web API to indicate the features and resources that it exposes, and a client application can submit requests that are directed to a specific version of a feature or resource," says Microsoft documentation. The company provides more guidance in OpenAPI document generation in .NET 9.
[Click on image for larger view.] OpenAPI (source: OpenAPI).
While this isn't the fun stuff, it's the important stuff, you come to find out later if you don't do it.
So to help avoid API versioning/documentation regret, expert ASP.NET Core developer and Microsoft MVP Philip Japikse will be presenting a session on just that topic, aptly titled "Versioning and Documenting ASP.NET Core Services," at the upcoming Visual Studio Live! developer conference coming to Las Vegas in March.
Japikse, also a CTO, Chief Architect, and international keynote speaker, will helm a 75-minute intermediate-level session that shows how easy it actually is to version and document APIs, promising that attendees will learn how to:
- Version ASP.NET Core RESTful services
- Document ASP.NET Core RESTful services
- Fix swagger to work with versioning
We caught up with Japikse to learn more about his session and how attendees can prepare for it.
VisualStudioMagazine: What inspired you to present a session on this topic?
Japikse: Two reasons. The first is that we build a lot of APIs for internal consumption, and having good OpenAPI documentation is a must. With good docs, teams can create clients for the APIs faster, as they don't have to wait for humans to communicate.
"We build a lot of APIs for internal consumption, and having good OpenAPI documentation is a must. With good docs, teams can create clients for the APIs faster, as they don't have to wait for humans to communicate. "
Philip Japikse, Developer, Coach, Author, Teacher
Versioning is also necessary as our APIs continue to evolve, and the client apps must continue working with the version they were developed for as new features are added/updated in newer versions.
The second reason is that we send data to other firms via APIs, and most don't employ versioning or OpenAPI documentation. We know how that adds extra time to the initial development cycle and have experienced broken API calls due to changes that aren't isolated with versioning.
What's one key challenge developers face when documenting ASP.NET Core API services, and how does your session address that challenge?
Documenting an API that is not versioned is very straightforward, and many tools enable the creation of the JSON documentation file. It gets more complicated when you add OpenAPI documentation for a versioned API. This is where all of the tools fail a bit and need help. In this session, I will show you how to add a JSON file for every version in your API and how to update the UI to enable the selection of each version of the file.
Can you preview a best practice for versioning API services in ASP.NET Core, as discussed in your presentation?
Sure. If you are changing your API in any way, you need to introduce a new version. We dive into the details of that statement in my session.
In your experience, what common pitfalls should developers avoid when implementing API services with ASP.NET Core?
When creating a versioned API, I think there's a common problem with architecting the code to support different versions, mainly when a significant portion of the API hasn't changed. When I was consulting, I saw a lot of copy-paste development. In my session, I cover supporting multiple versions without repeating code.
How does Swagger fit into your presentation?
I use Swagger to generate the JSON files and the UI to present them. The new tooling from Microsoft is very promising but not yet feature-complete.
What resources would you recommend for developers to get up to speed with documenting and versioning API Services with ASP.NET Core and prepare for your session?
Well, I can always shamelessly plug my last book, "Pro C# 10 with .NET 6" (Apress) 😁. In all seriousness, if you know how to build APIs using ASP.NET Core, I will teach you what you need to know to add versioning and documentation to your APIs.
Note: Those wishing to attend the conference can save hundreds of dollars by registering early, according to the event's pricing page. "Save $500 when you Register by the Cyber Savings deadline of Dec. 13," said the organizer of the event, which is presented by the parent company of Visual Studio Magazine.
About the Author
David Ramel is an editor and writer at Converge 360.