Building Your First Web API with .NET Core and Suave.io

The great thing about a new technology platform is we are afforded the rare chance to rethink the way we solve our problems.

Of course, we could do the grunt work of porting our existing codebase to the new platform and happily go about doing things the way we’ve always done them, but in doing so are we really taking advantage of this rare opportunity?

Shouldn’t a new platform have to justify itself by enabling us to solve our problems easier, faster, safer, and just plain better than how we solved them in the past?

A Web Api the Way We’ve Always Done Web Apis

A new platform wouldn’t be new without a set of sparkling new tutorials on how to do things the new way, here is the tutorial for Building Your First Web API with ASP.NET Core MVC and Visual Studio.

Reading through the tutorial and it’s pretty much the exact same way we built web apis on .Net Legacy. We have controllers, attributes on classes, attributes on methods, and lots and lots of infrastructure binding these classes and methods to our http pipeline.

It’s a good thing I know C#, and attributes, and MVC, and Asp.net when reading through this tutorial, because what our program does and the route it takes to solve our problem sure ain’t obvious.

In fact, the easiest thing to understand in this program is the documentation of what the program does.

These methods implement the two GET methods:

GET /api/todo

GET /api/todo/{id}

Wouldn’t it be great if this simple documentation was our program instead?

Let’s set a challenge for ourselves, let’s write a controller that is as close to our documentation as possible. In fact, let’s write a controller that is so similar to our documentation that it becomes self documenting.

Introducing Suave.io

Suave is a lightweight, non-blocking web server. The non-blocking I/O model is efficient and suitable for building fast, scalable network applications.

The above is from the Suave.io web site and let’s us know that that Suave does pretty much what ASP.NET MVC (*important technology because of all the capital letters) does, we use the library to write web apis that handle http requests and deliver http responses to our clients.

However, what’s different about Suave is how we route those requests.

Suave bundles together all the state of our application, so the http request, the response, our server configuration, and a few more odds and ends are all bundled up together as an http context.

This context is then passed to a function that either acts upon it and returns a new modified context, or says “nope” I can’t do anything with this context.

As we want our web server to be non-blocking, Suave ensures that all the work done inside this function is asynchronous.

Suave calls this function a Web Part and here is it’s definition.

type WebPart = HttpContext -> Async<HttpContext option>

Web Api Tutorial the Suave Way

This is all pretty abstract so far, so what we’ll do is go through the same tutorial from Building Your First Web API with ASP.NET Core MVC and Visual Studio, but instead implement using suave.

Add a model class

Let’s quickly define ourselves a TodoItem type.

Add a repository

And encapsulate our data access logic with the requisite repository to store and retrieve TodoItems from a dictionary.

Register the repository

We’ll skip over this state for now as later we’ll use partial application to inject a dependency into our controller.

Add a controller

Following along with the tutorial, we add a controller to handle our requests and use the repository to change the persistent state of our applicaiton.

A self documenting web controller

We can go into the details of the code another time so for now just glaze over everything you’ve seen and concentrate on the last bit of code where we define our todoController.

Without knowing a lick of f# code, I bet you can suss out what that code is doing as it’s very close to our idealized documentation.

Our code is documenting what paths our program takes, what we do when we come to end of a path, and what dependencies we rely on to do the work at the end of these paths.

Even as we add more controllers, we can easily see what paths we are taking, why we are taking them, and what we do at the end of the path. Our code becomes a self documenting tree of what our program is doing.

Why Now is the Time For a New Way of Thinking

As technology professionals we very rarely get a chance to do things in a new way. Often our time is spent supporting decisions that were made a long time ago.

A new platform is a rare chance to make a new set of decisions that will be handed down to a new generation of technology professionals to support and maintain.

.Net Core allows us to right the mistakes we made in .Net Legacy and what I hope is this simple example will pique your curiosity in Suave as a better way of solving our problems on this new platform.

The Rest of the Code

You can find the entire solution and test it out with postman in the following Github Repository. There are plenty of interesting things to talk about but we’ll save that for another time.