How to Consume RESTful APIs in C#

RESTful APIs (Representational State Transfer) are a popular way to facilitate communication between applications, allowing them to share data over HTTP.

What is a RESTful API?

A RESTful API is a service that adheres to the principles of REST (Representational State Transfer), which is an architectural style for designing networked applications. RESTful APIs use HTTP requests to perform CRUD operations Create, Read, Update, and Delete on data.

APIs act as intermediaries between software applications. When you send a request to an API, it processes the request and returns a response (usually in JSON or XML format). RESTful APIs are stateless, meaning every request contains all the necessary information, and no session data is stored between requests.

Ways to Consume RESTful APIs in C#

There are several libraries and tools available in C# for consuming RESTful APIs.

1. HttpWebRequest/Response Class

The HttpWebRequest class offers detailed control over request-making, which can be both a benefit and a potential time sink depending on your needs. It ensures a non-blocking user interface and works with the HttpWebResponse class to handle incoming responses.

For example, how to use HttpWebRequest to make a GET request:

public class HttpWebRequestHandler : IRequestHandler
{
    public string Get(string url)
    {
        var request = (HttpWebRequest)WebRequest.Create(url);
        request.Method = "GET";
        request.UserAgent = "Mozilla/5.0";
        request.AutomaticDecompression = DecompressionMethods.Deflate | DecompressionMethods.GZip;
        string content = string.Empty;
        using (var response = (HttpWebResponse)request.GetResponse())
        {
            using (var stream = response.GetResponseStream())
            {
                using (var sr = new StreamReader(stream))
                {
                    content = sr.ReadToEnd();
                }
            }
        }
        return content;
    }
}

This approach gives you control over every aspect of the HTTP request, but it can get complex when dealing with advanced scenarios such as posting data or handling authentication.

2. WebClient Class

The WebClient class is a simplified wrapper around HttpWebRequest, abstracting its complexities. It allows for easier, less error-prone code, making it a good choice when minimizing code and simplicity matter more than execution speed.

For example, how to use WebClient to fetch data:

public string Get(string url)
{
    var client = new WebClient();
    client.Headers.Add("User-Agent", "Mozilla/5.0");
    var response = client.DownloadString(url);
    return response;
}

With WebClient, tasks like downloading strings or files are much easier, but the trade-off is that it may not offer the flexibility needed for complex use cases.

3. HttpClient Class

HttpClient is the modern approach for making HTTP requests in .NET, providing built-in support for asynchronous operations, persistent connections, and various advanced features like request caching.

For example, using HttpClient to fetch data synchronously:

public string Get(string url)
{
    using (var httpClient = new HttpClient())
    {
        httpClient.DefaultRequestHeaders.Add("User-Agent", "Mozilla/5.0");
        var response = httpClient.GetStringAsync(new Uri(url)).Result;
        return response;
    }
}

HttpClient should ideally be used asynchronously, and it’s important to note that it’s recommended to reuse a single instance of HttpClient for the duration of the application to avoid socket exceptions.

4. RestSharp

RestSharp is a modern, open-source .NET library available via NuGet, offering a user-friendly alternative to standard libraries like HttpClient. It supports older .NET Framework versions, provides built-in authentication and serialization/deserialization (with customization options), and works across platforms. RestSharp supports various authentication methods, including OAuth1, OAuth2, Basic, NTLM, and parameter-based, and allows both synchronous and asynchronous operations.

For example:

public string Get(string url)
{
    var client = new RestClient(url);
    var response = client.Execute(new RestRequest());
    return response.Content;
}

For example, how to deserialize the response directly:

public List<Book> Get(string url)
{
    var client = new RestClient(url);
    var response = client.Execute<List<Book>>(new RestRequest());
    return response.Data;
}

RestSharp is a powerful and flexible library that can save you a lot of time when working with RESTful APIs.

5. ServiceStack HTTP Utils

ServiceStack is another popular library for consuming APIs.

For example, how to use ServiceStack’s HTTP Utils to fetch data:

public string Get(string url)
{
    var response = url.GetJsonFromUrl(webReq =>
    {
        webReq.UserAgent = "Mozilla/5.0";
    });
    return response;
}

You can also deserialize the response immediately using ServiceStack’s FromJson method:

public List<Book> Get(string url)
{
    var releases = url.GetJsonFromUrl(webReq =>
    {
        webReq.UserAgent = "Mozilla/5.0";
    }).FromJson<List<Book>>();
    return releases;
}

ServiceStack offers a clean, simple, and well-maintained solution for interacting with third-party REST APIs.

6. Flurl

Flurl is a modern and intuitive library for building HTTP requests with a fluent API. It enhances the standard HttpClient by adding chaining methods for improved readability and maintainability.

For example, using Flurl to consume a RESTful API:

// Flurl will use one HttpClient instance per host
var product = await "https://api.example.com"
    .AppendPathSegment("product")
    .SetQueryParams(new { category = "electronics", limit = 10 })
    .WithOAuthBearerToken("your_oauth_token")
    .PostJsonAsync(new
    {
        name = "Smartphone",
        price = 499
    })
    .ReceiveJson<Product>();

As you can see, Flurl allows for method chaining that creates a readable and intuitive flow. In the background, Flurl enhances the HttpClient library, making it asynchronous and easier to use.

We can interact with Flurl in two primary ways:

public string GetProductInfo(string url)
{
    var result = url
        .WithHeader("User-Agent", "YourApp")
        .GetJsonAsync<List<Product>>()
        .Result; // Blocking synchronous call (not recommended)
    return JsonConvert.SerializeObject(result);
}

Although the above approach works, it's not ideal because we're serializing the response only to deserialize it again later.

public List<Product> GetDeserializedProductInfo(string url)
{
    var result = url
        .WithHeader("User-Agent", "YourApp")
        .GetJsonAsync<List<Product>>()
        .Result; // Still blocking (avoid in production)
    return result;
}

However, the best practice would be to use the async method, which takes full advantage of Flurl's capabilities:

public async Task<List<Product>> GetDeserializedProductInfoAsync(string url)
{
    var result = await url
        .WithHeader("User-Agent", "YourApp")
        .GetJsonAsync<List<Product>>();
    return result;
}

Flurl’s fluent API makes building requests easy and readable, making it a great choice for developers who prefer clean, declarative code.

7. DalSoft.RestClient

DalSoft.RestClient is a dynamic and flexible library for consuming REST APIs. It allows you to construct URLs dynamically and automatically deserializes responses.

To get started, you can download DalSoft.RestClient in one of two ways:

• Using the NuGet Package Manager by running the following command: Install-Package DalSoft.RestClient
• Or via the .NET Core CLI by executing: dotnet add package DalSoft.RestClient

For example, using DalSoft.RestClient:

public async Task<List<Book>> Get(string url)
{
    dynamic client = new RestClient(RequestConstants.BaseUrl,
        new Headers { { "User-Agent", "Mozilla/5.0" } });
    var response = await client.repos.restsharp.restsharp.releases.Get();
    return response;
}

DalSoft.RestClient uses dynamic typing to make it easy to construct requests without worrying about URL formatting. It automatically handles response deserialization, making it a convenient choice for developers who want a flexible, type-safe solution.