Q&A

Philip Japikse's Deep Dive into Web Services with ASP.NET Core

• By David Ramel
• 02/02/2023

Entire books have been written about creating and using web services in ASP.NET Core, so how does one explain such a huge topic in a single tech event presentation? You expand the session into a nearly three-hour, intermediate-level deep dive.

That's what renowned web-dev expert Philip Japikse will do next month in a big, in-person VSLive! event being held in Las Vegas March 19-24.

In a two-part session titled Web Services with ASP.NET Core Deep Dive on March 23, it will all be covered by Japikse, a developer, coach, author, teacher and holder of Microsoft MVP, ASPInsider, MCSD, PSM II, PSD and PST credentials.

Central to the presentation are APIs, which in ASP.NET Core come in two kinds: controller-based APIs and minimal APIs, with the latter simply helping developers use the absolute minimum number of components or dependencies required to create HTTP APIs.

Also key are RESTful services used in an architectural style where web services receive and send data from and to client apps with a goal of centralizing data that different client apps will use.

For the nuts and bolts of his presentation, Japikse will cover building and configuring the web host, dependency injection and the options pattern, environmental awareness and configuration, logging with Serilog, and controllers/routing. He will also discuss explicit and implicit model binding and validation, followed by detailing functionality added when using the ApiController attribute, including binding source parameter inference and how to customize the provided behavior. What's more, time in the deep dive will be devoted to versioning APIs, documentation with Open API, and making sure the two work well together. And, of course, securing your API with basic authentication will be a focal point.

To learn more about all that, we caught up with Japikse for a short Q&A ahead of his presentation:

VisualStudioMagazine: What's the No. 1 consideration for developers starting out to build RESTful services with ASP.NET Core?
Japikse: The biggest part of building a service is to understand that you are building a service. I know that sounds rather obvious (and maybe a little silly), but so many times I've seen people and teams build extremely chatty APIs with a very large number of endpoints. When working with teams to get their APIs under control, we discover that a lot of endpoints can be combined using route parameters, headers, or even adjusting the JSON payload. The more complicated your system is, the less likely that it will be used successfully and the more difficult it will be to maintain and properly version.

The amount of code can usually be reduced by taking advantage of the inheritance capabilities in ASP.NET Core/.NET/C#, as I show in my session. Here is a class diagram of the base crud controller and the inherited Cars controller.

Notice there is only one extra endpoint on the Cars controller. The standard CRUD operations are handled in the base controller.

How have .NET 6 and ASP.NET Core 6 changed the game?
Before covering ASP.NET Core improvements for building RESTful services, a little history is important. The real game changer for creating services in the .NET ecosystem was the release of ASP.NET WebAPI. Prior to WebAPI, .NET services were built using ASMX services or Windows Communication Foundation (WCF). Services using ASMX web methods were very limited, and while WCF was (and still is) a solid framework, it can be overkill for a lot of API needs. Heavily leveraging ASP.NET MVC, WebAPI brought the concept of MVC (minus the view, of course) to building RESTful services, reducing complexity and development time for many projects.

Building services in ASP.NET Core is conceptually the same as building services in WebAPI, but with a ton of improvements (as I cover in this extended session). In addition to improvements in configuration, deployment, versioning, and OpenAPI integration, ASP.NET Core 6 is an order of magnitude faster than previous versions. ASP.NET Core changed the game for all web development and has matured to contain pretty much all we need without growing stale or over developed.

What's expected with .NET 7 and ASP.NET Core 7 in that regard?
Speed, speed, and more speed. Most of the "bullet point list of work" in ASP.NET Core 7 went into Blazor with some work in minimal APIs, but the biggest change is additional speed improvements.

What other specific new tooling has Microsoft introduced to help?
Besides EF Core (our go-to ORM for creating data access layers for our APIs), Microsoft has provided NuGet packages for versioning and documenting your APIs.

How do developers get API versioning and Open API to work together well?
By coming to my session 😊. All snark aside, there is an issue that causes a problem with the "out of the box" integration of Swagger and versioning, but it's well documented by Microsoft, sample code is provided to solve it, and I cover this in my session.

When integrated correctly, you get the option to select the version on the SwaggerUI page:

Why is it important to document services with Swagger?
It is the software manual for how to call into your service. Swagger UI provides a working sample where your code can be tested, like this:

In addition to the human aspect of creating a documentation and test platform, the raw swagger.json file can be used to scaffold the calling code. This is helpful if (for example) the service is behind a firewall/paywall that your team doesn't have access to yet, but you need to start building your integrations.

What question should we have asked?
The importance of versioning. APIs are not consumed by humans, but software. On a web page, if you move a button, the human using your webpage can just adjust where they click. In an API, if you change how something works, the calling code will fail.

Without good logging and notification processes, this failure could go on for quite some time. APIs should follow the principle of least surprise. If something is changing, then it's version needs to be changed. This also helps communicate deprecation of a version, so developers (if they look in the headers) will know to move on from the deprecated version.