By taking a path of Web development, you find yourself in the need of dealing with external

APIs (Application Programming Interface) sooner or later. In this article, my goal is to make
the most comprehensive list of ways to consume RESTful APIs in your C# projects and
show you how to do that on some simple examples. After reading the article you will have
more insight which options are available to you and how to choose the right one next time
you need to consume a RESTful API.

What is a RESTful API?

So, before we start, you might be wondering what does API stand for, and what is the RESTful part
all about?

To put things simply, APIs are the layers between software applications. You can send the request to
the API, and in return, you get the response from it. APIs hide all the nitty-gritty details of the
concrete implementation of a software application and expose the interface you should use to
communicate with that application.

The whole internet is the one big spider web made of APIs. We use APIs to communicate and relate
information between applications. We have an API for pretty much anything out there. Most of the
services you use daily have their own APIs (GoogleMaps, Facebook, Twitter, Instagram, weather
portals…)

RESTful part means that API is implemented in accordance with the principles and rules of the
REST (Representational State Transfer) which is the underlying architectural principle of the web.
RESTful APIs in most cases return the plain text, JSON or XML response. Explaining REST in more
detail is out of the scope of this article, but you can read more about REST in our article Top REST
API best practices.
How to Consume RESTful APIs
Ok, let’s go to the meaty part of this whole story.

There are several ways to consume a RESTful API in C#:

  HttpWebRequest/Response Class
 WebClient Class
 HttpClient Class
 RestSharp NuGet Package
 ServiceStack Http Utils
 Flurl
 DalSoft.RestClient
Every one of these has pros and cons, so let us go through them and see what they offer.

As an example, we will be collecting information about RestSharp repo releases and their publish
dates via GitHub API. This information is available publicly and you can see how raw JSON
response looks here: RestSharp releases
We are going to utilize the help of the Json.NET library to deserialize the response we get. Also, for
some examples, we are going to use the inbuilt deserialization mechanisms of the libraries. It’s up to
you to choose which way you prefer because no way is the right way. (You can see the
implementation for both mechanisms in the source code).
What I expect to get as a result of the next few examples is a deserialized JArray (for simplicity)
that contains RestSharp release information. After that, we can iterate through it to get the following
result.

HttpWebRequest/Response Class
It’s the HTTP-specific implementation of WebRequest class which was originally used to deal with
HTTP requests, but it was made obsolete and replaced by the WebClient class.
The HttpWebRequest class offers fine-grained control over every aspect of the request
making process. As you can imagine, this can be the double-edged sword and you can easily end up
losing enormous amounts of time fine-tuning your requests. On the other hand, this might just be
what you need for your specific case.
HttpWebRequest class does not block the user interface, which is, I am sure you will agree with this

one, pretty important.

HttpWebResponse class provides a container for the incoming responses.

This is a simple example of how to consume an API using these classes.

1 public class HttpWebRequestHandler : IRequestHandler

2 {
3 public string GetReleases(string url)
4 {
5 var request = (HttpWebRequest)WebRequest.Create(url);
6
7 request.Method = "GET";
8 request.UserAgent = RequestConstants.UserAgentValue;
9 request.AutomaticDecompression = DecompressionMethods.Deflate | DecompressionMethods.GZip;
10
11 var content = string.Empty;
12
13 using (var response = (HttpWebResponse)request.GetResponse())
14 {
15 using (var stream = response.GetResponseStream())
16 {
17 using (var sr = new StreamReader(stream))
18 {
19 content = sr.ReadToEnd();
20 }
21 }
22 }
23
24 return content;
25 }
26 }

Although a simple example, it becomes much more complicated when you need to deal with more
sophisticated scenarios like posting form information, authorizing etc.

WebClient Class
This class is a wrapper around HttpWebRequest. It simplifies the process by abstracting the details
of the HttpWebRequest from the developer. The code is easier to write and you are less likely to
make mistakes this way. If you want to write less code, not worry about all the details, and the
execution speed is a non-factor, consider using WebClient class.
This example should give you the rough idea how much easier is to use WebClient compared to
the HttpWebRequest/HttpWebResponse approach.
1 public string GetReleases(string url)
2{
3 var client = new WebClient();
4 client.Headers.Add(RequestConstants.UserAgent, RequestConstants.UserAgentValue);
5
6 var response = client.DownloadString(url);
7
8 return response;
9}

Much easier, right?

Other then DownloadString method, WebClient class offers a host of other useful methods to
make our life easier. We can easily manipulate strings, files or byte arrays using it, and for a price of
just a few milliseconds slower than HttpWebRequest/HttpWebResponse approach.
Both the HttpWebRequest/HttpWebResponse and WebClient classes are available in the older
versions of .NET. Be sure to check out the MSDN if you are interested what else WebClient has to
offer.
HttpClient Class
HttpClient is the “new kid on the block”, and offers some of the modern .NET functionalities that

older libraries lack. For example, you can send multiple requests with the single instance
of HttpClient, it is not tied to the particular HTTP server or host, makes use of async/await
mechanism.
You can find out about the five good reasons to use HttpClient in this video:
 Strongly typed headers.

 Shared Caches, cookies, and credentials

 Access to cookies and shared cookies

 Control over caching and shared cache.

 Inject your code module into the ASP.NET pipeline. Cleaner and modular code.

Here is HttpClient in action in our example:

1 public string GetReleases(string url)
2 {
3 using (var httpClient = new HttpClient())
4 {
5 httpClient.DefaultRequestHeaders.Add(RequestConstants.UserAgent, RequestConstants.UserAgentValue);
6
7 var response = httpClient.GetStringAsync(new Uri(url)).Result;
8
9 return response;
10 }
11 }

For the simplicity’s sake, I implemented it synchronously. Every HttpClient method is meant to be
used asynchronously and SHOULD be used that way.
Also, I need to mention one more thing. There is a debate whether HttpClient should be
wrapped in a using block or statically on the app level. Although it implements IDisposable, it
seems that by wrapping it in the using block you can make your app malfunction and get the
SocketException. And as Ankit blogs, the performance test results are much in favor of static
initialization of the HttpClient. Be sure to read these blog posts as they can help you be more
informed about the correct usage of the HttpClient library.
And don’t forget, being modern, HttpClient is exclusive to the .NET 4.5, so you might have
trouble using it on some legacy projects.
RestSharp
RestSharp is the OpenSource alternative to standard .NET libraries and one of the coolest .NET
libraries out there. It is available as a NuGet package, and there are a few reasons why you should
consider trying it out.

Like HttpClient, RestSharp is a modern and comprehensive library, easy and pleasant to use, while
still having support for older versions of .NET Framework. It has
inbuilt Authentication and Serialization/Deserialization mechanisms but allows you to override them
with your custom ones. It is available across platforms and supports OAuth1, OAuth2, Basic, NTLM
and Parameter-based Authentication. You can choose to work both synchronously or
asynchronously. There is a lot more to this library, and these are just some of the great benefits it
offers. For the detailed information on usage and capabilities of RestSharp, you can visit the
RestSharp page on GitHub.

Now let’s try to get a list of RestSharp releases using RestSharp

C#
1 public string GetReleases(string url)
2{
3 var client = new RestClient(url);
4
5 var response = client.Execute(new RestRequest());
6
7 return response.Content;
8}

Simple enough. But don’t let that fool you, RestSharp is very flexible and has all the tools you need
to achieve almost anything while working with RESTful API.

One thing to note in this example is that I didn’t use RestSharp’s deserialization mechanism due to
the example consistency, which is a bit of a waste, but I encourage you to use it as it is really easy
and convenient. So you can easily make a container like this:

C#
1 public class GitHubRelease
2{
3 [JsonProperty(PropertyName = "name")]
4 public string Name { get; set; }
5 [JsonProperty(PropertyName = "published_at")]
6 public string PublishedAt { get; set; }
7}

And after that use Execute method to directly deserialize the response to that container. You can add
just the properties you need and use attribute JsonProperty to map them to C# properties (nice
touch). Since we get the list of releases in our response, we use the List<Release> as a containing
type.
C#
1 public List<GitHubRelease> GetDeserializedReleases(string url)
2{
3 var client = new RestClient(url);
4
5 var response = client.Execute<List<GitHubRelease>>(new RestRequest());
6
7 return response.Data;
8}

Pretty straightforward and elegant way to get our data.

There is a lot more to RestSharp than sending GET requests, so explore and see for yourself how cool
it can be.
One final note to add to the RestSharp case is that its repository is in need of maintainers. If you want
to learn more about this cool library, I urge you to head over to RestSharp repo and help this project
stay alive and be even better. You can also help porting RestSharp to .NET Core.
ServiceStack Http Utils
Another library, but unlike RestSharp, ServiceStack seems to be properly maintained and keeping the
pace with modern API trends. List of ServiceStack features is impressive and it certainly has various
applications.

What is most useful to us here is to demonstrate how to consume an external RESTful API.
ServiceStack has a specialized way of dealing with 3rd Party HTTP APIs called Http Utils.
Let us see how fetching RestSharp releases looks like using ServiceStack Http Utils first using the
Json.NET parser.

C#
1 public string GetReleases(string url)
2{
3 var response = url.GetJsonFromUrl(webReq =>
4 {
5 webReq.UserAgent = RequestConstants.UserAgentValue;
6 });
7
8 return response;
9}

You can also choose to leave it to the ServiceStack parser. We can reuse the Release class defined
earlier in the post.
C#
1 public List<GitHubRelease> GetDeserializedReleases(string url)
2{
3 var releases = url.GetJsonFromUrl(webReq =>
4 {
5 webReq.UserAgent = RequestConstants.UserAgentValue;
6 }).FromJson<List<GitHubRelease>>();
7
8 return releases;
9}

As you can see, either way works fine, and you can choose whether you get the string response or
deserialize it immediately.
Although ServiceStack is the last library we stumbled upon, we were pleasantly surprised how easy it
was for me to use it, and I think it may become my go-to tool for dealing with APIs and services in
the future.

Flurl
One of the libraries requested by many people in the comments section, and loved by many all over
the internet but still gaining traction.

Flurl stands for Fluent Url Builder, which is the way the library builds its queries. For those of you
not familiar with the fluent way of doing stuff, fluent simply means that library is built in such a way
that methods are chained to achieve greater readability, similar to that of human language.

To make things even easier to understand, let’s give some examples (this one is from official docs):

The fluent way

C#
1 // Flurl will use 1 HttpClient instance per host
2 var person = await "https://api.com"
3 .AppendPathSegment("person")
4 .SetQueryParams(new { a = 1, b = 2 })
5 .WithOAuthBearerToken("my_oauth_token")
6 .PostJsonAsync(new
7 {
8 first_name = "Claire",
9 last_name = "Underwood"
10 })
11 .ReceiveJson<Person>();

You can see how the methods chain together to complete the “sentence”.

In the background, Flurl is using HttpClient or rather enhancing HttpClient library with its own
syntactic sugar. So that means Flurl is an async library and it’s good to have that in mind.

As with other advanced libraries, we can do this in two different ways:

Synchronous code
C#
1 public string GetReleases(string url)
2{
3 var result = url
4 .WithHeader(RequestConstants.UserAgent, RequestConstants.UserAgentValue)
5 .GetJsonAsync<List<GitHubRelease>>()
6 .Result;
7
8 return JsonConvert.SerializeObject(result);
9}

This way is rather terrible since we are serializing result only to deserialize it a little bit later. If you
are using a library such as Flurl, you shouldn’t be doing things this way.

A better way of doing things would be:

C#
1 public List<GitHubRelease> GetDeserializedReleases(string url)
2{
3 var result = url
4 .WithHeader(RequestConstants.UserAgent, RequestConstants.UserAgentValue)
5 .GetJsonAsync<List<GitHubRelease>>()
6 .Result;
7
8 return result;
9}

With .Result we are forcing synchronous behavior of the code. The real and intended way to use
Flurl would look like this:

The best way of using Flurl

C#
1 public async Task<List<GitHubRelease>> GetDeserializedReleases(string url)
2{
3 var result = await url
4 .WithHeader(RequestConstants.UserAgent, RequestConstants.UserAgentValue)
5 .GetJsonAsync<List<GitHubRelease>>();
6
7 return result;
8}

Which shows off the full potential of the Flurl library.

If you want to learn more about how to use Flurl in different real-life scenarios, check out
our Consuming GitHub API (REST) With Flurl article
In summary, it’s like advertised: easy to use, modern, readable and testable. What more can you
expect of a library? To be open source? Check out: Flurl repo and contribute if you like it!
DalSoft.RestClient
Now this one is a bit different than anything on this list so far. But this one does it a bit differently.
Let’s see how we can use DalSoft.RestClient to consume the GitHub API and then talk about what
we’ve done.

First things first, you can download DalSoft.RestClient either via NuGet Package Manager by typing
: Install-Package DalSoft.RestClient
or via .NET Core CLI: dotnet add package DalSoft.RestClient
Either way is fine.

Once we have our library, we can do something like this:

C#
1 public string GetReleases(string url)
2{
3 dynamic client = new RestClient(RequestConstants.BaseUrl,
4 new Headers { { RequestConstants.UserAgent, RequestConstants.UserAgentValue } });
5
6 var response = client.repos.restsharp.restsharp.releases.Get().Result.ToString();
7
8 return response;
9}

or preferably by using DalSoft.RestClient to deserialize the response immediately while utilizing its
full power:

Deserialized response
C#
1 public async Task<List<GitHubRelease>> GetDeserializedReleases(string url)
2{
3 dynamic client = new RestClient(RequestConstants.BaseUrl,
4 new Headers { { RequestConstants.UserAgent, RequestConstants.UserAgentValue } });
5
6 var response = await client.repos.restsharp.restsharp.releases.Get();
7
8 return response;
9}

So, let’s talk about these examples a bit.

At first glance, it doesn’t seem much simpler than some other modern libraries that we’ve used.

But it comes down to the way form our requests and that’s by utilizing the dynamic nature of our
RestClient. For example, our BaseUrl is https://api.github.com and we need to get to
the https://api.github.com/repos/restsharp/restsharp/releases. We can do that by
creating our client dynamically and then forming the Url by chaining “parts” of the Url:
Chaining
C#
1 await client.repos.restsharp.restsharp.releases.Get();

A pretty unique way to form a request. And a very flexible one too!

So, once we have our base Url set, we can play with different endpoints easily.

It’s also worth mentioning that JSON response we get is being automatically type-casted. As you can
see in the second example, the return value of our method is Task<List<GitHubReleases>>. So
the library is smart enough to cast the response to our type (relying on Json.NET). That makes our
life much easier.
Besides being easy to understand and use, DalSoft.RestClient has everything a modern library should
have. It is configurable, asynchronous, extensible, testable and it supports multiple platforms.
We’ve demonstrated just a small portion of the DalSoft.RestClient features. If this got you interested
in using DalSoft.RestClient, head over to our article about it to learn how to use it in different
scenarios or refer to official GitHub repo and documentation.
Other Options
There are a lot of other options available for your specific problems. You can use any of these
libraries to consume a specific RESTful API. For example, octokit.net is used to work with GitHub
API specifically, Facebook SDK is used for consuming Facebook API and there are many others for
almost anything.
While these libraries are made specifically for those APIs and may be great at doing what they are
meant for, their usefulness is limited because you often need to connect with more than one API in
your applications. This may result in having different implementations for each one, and more
dependencies which potentially leads to repetitiveness and is error-prone. The more specific the
library, the less flexibility it has.