Anybody that has built HTTP or REST APIs, has had to deal with things like OpenAPI or Swagger. Those are reasonably trivial to implement using ASP.NET Core, and you even get a nice Swagger UI website out of the box.

Just like any interface or programmatic contract, there are plenty of aspects that need careful analysis. Think of comprehensive online documentation for your APIs, using HTTP error codes appropriately, and providing clarity on what fields in the JSON are required and which are optional or can be empty. And don't forget versioning. Allowing a developer to view and switch between the supported versions and make it clear what APIs are deprecated isn't as trivial as you may think.

In this talk, I'll show you everything that you might need to know about building nicely documented, properly versioned HTTP APIs that make your consumers happy.

* What are important elements of a good HTTP API
* What HTTP error codes should be used for what
* Options for versioning HTTP APIs (url, query parameters, headers)
* Capturing all of this in ASP.NET Core using attributes, XML comments, and the versioning APIs
* Adding customizations to support marking APIs as obsolete and switching between versions