In our article A Few Great Ways to Consume RESTful API in C# we introduced a few different ways to consume a Restful API.

This article is about going into details of Flurl library and giving a few examples of how to authenticate and consume a restful API such as GitHub’s.

The source code for this article is located here: Flurl Examples. Be sure to fork it and follow along with this article to make most out of it.

In this article you’ll learn:

So, let’s drill down into it.

So, What is Flurl?

Flurl stands for Fluent URL.

Quoting Flurl’s home page: Flurl is a modern, fluent, asynchronous, testable, portable, buzzword-laden URL builder and HTTP client library for .NET. 

It’s simple as that.

Flurl has been recommended by a few of our readers, and upon further investigation and usage, we’ve concluded that it is indeed library worth using or at least trying. Our experience with Flurl was positive, it’s really easy to set up and use, and the documentation is digestible and on point.

Under the polished hood of a modern library lies HttpClient. That means all methods are by default asynchronous, but with the added goodness of fluent execution.

Flurl also has its own mechanisms for testing, so writing complicated mocks and test cases has become a non-issue. We’ll get to that later on.

Since Flurl is completely fluent and relies on extension methods, that means, you’ve guessed it, it’s completely extensible.

It has it’s own configuration and error handling mechanisms, which makes it a complete and very intuitive library.

So, that’s about it in short terms, now let’s get started, and see what Flurl can do for us.

Setting up Flurl

You can add Flurl to your project by typing Install-Package Flurl -Version 2.8.0 in your package manager console, or by using .NET CLI: dotnet add package Flurl --version 2.8.0.

And you’re good to go! Easy as that.

What does Flurl Offer?

Flurl consists of two main modules: URL builder and some utility methods as well as Flurl.HTTP which is the main part and we’ll be using that to consume our APIs.

URL Builder

Flurl’s URL API can help you easily construct your URLs.

For example, you can do something like this to construct a complicated URL:

Flurl offers great ways to parse, encode and combine URLs. There is a list of methods you can utilize here.

So that’s how you manipulate URLs with Flurl.

HTTP

Once that you have your URL neatly prepared, you can dive into Flurl’s HTTP features.

With Flurl, you can consume any REST endpoint, whether public or private. You can send GET, POST, PUT, PATCH or DELETE requests and set up headers, cookies and much more.

All responses are awaitable and you can force a strongly-typed response or just return a result as a dynamic object if you prefer it that way.

Flurl works well with strings, bytes, streams or any other media type, and you can both return HttpResponseMessage or the data from its body.

We’ll get to that in the examples section.

Configuration

Let’s get on with the configuration.

Now, the configuration of Flurl is available at different levels. While most people don’t need to configure their applications and are pretty much satisfied with the default library behavior, there are different levels of configuration in Flurl that will let you mold it exactly how you like it.

The stuff you can configure:

  • Client settings
  • Requests settings
  • Tests settings
  • The way HttpClient is handled
  • Serializers
  • Caching strategy

As we mentioned, it’s highly unlikely that you’ll need to configure some of these settings, especially if you are not sure what they do. This goes beyond the scope of this article and it can be a whole topic to itself.

But this goes to show just how powerful Flurl can be despite the simplistic view on the surface.

Eventing

Besides these settings, Flurl provides a way to decouple your business logic from Flurl itself through the Event mechanism. Events are available through the HttpCall class.

There is an example in official docs that show how to implement a global error handling mechanism with events (very useful).

Once you start changing different settings all over the place, you can revert them to default values using Settings.ResetDefaults() method.

Extensibility

Since Flurl is fluent by nature, which means it uses extension methods, we can add our own extensions as well if needed.

This gives Flurl almost god-like flexibility and natural extensibility that can fit everyone’s needs.

You can extend both the Url builder and Flurl.Http parts of the Flurl library.

Let’s extend Url builder:

Now we can do something like this:

Pretty slick.

We can also extend the Flurl.Http part. Flurl chainable methods come in sets of 3 or 4, so we can do something like this:

And then, our method is available through the fluent interface as a string, Url or IFlurlRequest extension:

If you are unfamiliar with extension methods, check out our tutorial about them.

Two Ways To Authenticate in Flurl

Of course, many APIs hide confidential resources behind protected endpoints. To get to that endpoints you need to have certain rights (authorization), and you do that by authenticating yourself.

Flurl offers two ways of authenticating: Basic Authentication and OAuth 2.0 bearer token.

Here’s how you do it:

A very easy and intuitive way to authenticate!

Here is how it might look like in a real example:

This example shows us how to authenticate using Bearer token and retrieve the list of GitHub repositories.

The important thing to note here is that we store token in the environment variable. You should never, ever, store sensitive information in your code or configuration files. That’s a serious security risk!

Here is how authentication looks like using the Basic Authentication mechanism:

You see how easily we changed the authentication mechanism?

Very cool.

The same warning applies to storing usernames and passwords too. Keep them safe in your environment variables!

How to Write Get, Post, Put/Patch, and Delete Requests

Now to the main event, writing requests in Flurl.

This is where Flurl really shines. Fluent syntax, combined with the asynchronous execution and readability to match it really does the job.

Writing requests is really easy and the learning curve is almost non-existent!

Let’s see what it looks like in our example (we will use GitHub bearer token, but you can use the other mechanism too):

If you are unfamiliar with the GitHub tokens, there is a great resource about them.

Essentially, you need to follow the link above and generate one here:

Personal Access Tokens

Alternatively, you can use basic authentication as we described in the authentication section.

Exception Handling

Flurl.Http throws FlurlHttpException for every non-200 response.

You can easily deserialize Error response:

Or even allow other status codes:

Let’s see how a real-world example might look like:

In this scenario, we are trying to create a repository. If that repository already exists, we’ll get a FlurlHttpException wrapped in Aggregate exception back from GitHub API. So we need to cover that scenario and write our exception so we can figure out what happened.

And true enough, we get it:

FlurlHttpException

This is what we get as a result of trying to create the same repository twice.

Sweet.

Unit Testing in Flurl

Flurl has some “dead simple” ways of testing its functionalities, right out-of-the-box.

HttpTest class provides the mechanisms to test our API calls.

Here are some of the examples of a few tests using MSTest framework:

Despite what it looks like at first, these are all mock requests, and you won’t hit any real endpoints.

Very neat!

You can write tests in any other popular testing framework for .NET as well (NUnit, Xunit…). The choice is all yours.

If you prefer the notion of setting things up and tearing them down after the tests, you can do that too:

Arrange and assert phases are pretty flexible too. You can pretty much execute any scenario you can think of.

As an exercise you can play around with HttpTest class more, to see what else it can do!

Flurl Lifetime

Since Flurl.Http uses HttpClient under the hood, it relies on its lifetime too.

If you’ve ever worked with HttpClient, you are probably aware that it’s recommended that you instantiate it once per application lifetime because it can easily exhaust the number of sockets available.

Flurl (from the v2 up) handles that problem by caching the HttpClient for the same host. That means every succeeding request to the same host will use the same HttpClient instance.

Note that you need to upgrade to version 2+ to have this functionality available (recommended).

FlurlClient is a wrapper around HttpClient, so consequently, it’s bound to its lifetime.

You can have more control over HttpClient instances and their lifetimes you can do something like this:

Flurl and IoC

Dependency Injection and IoC containers play a great role in modern application development.

Flurl is well suited for dependency injection. Trying to register IFlurlClient as a singleton and services as transient, or any other combination can result in less than optimal results or bad practices.

That’s where IFlurlClientFactory comes in. As the official documentation states, the only reason it exists is to override Flurl’s instance-per-host default behavior.

So we can do something like this:

Now we can simply register IFlurlClientFactory as a singleton and get a single instance of FlurlClient for this service.

Dependency Injection is a whole topic to itself, so we won’t go any deeper into it in this article.

This should be enough if you need to register Flurl through your IoC of choice.

Conclusion

This wraps it up for out Flurl library introduction.

Flurl is a very a neat little library that gives us both simplicity and flexibility that we need to work comfortably with REST in our C# applications.

It is simple enough to easily learn and use, and it is extensible enough to cover some pretty complex scenarios.

So we hope this little demonstration will help you understand how Flurl works and maybe even persuade you to try it out. We will definitely use it in our newest projects that require REST communication.

To learn about more useful ways to communicate with REST endpoints, you can check our article: A Few Great Ways to Consume RESTful API in C#.

What you’ve learned in this post:

  • What Flurl is and what it can do for you
  • How to set it up, configure it, and extend it
  • How to build URLs and write requests with Flurl
  • A bit about Flurl lifetime (HttpClient)
  • How to unit test your Flurl methods

If you have enjoyed reading this article and if you would like to receive the notifications about the freshly published .NET Core content we encourage you to subscribe to our blog.