RestEase

RestEase is a little type-safe REST API client library for .NET Framework 4.5.2 and higher and .NET Platform Standard 1.1 and higher, which aims to make interacting with remote REST endpoints easy, without adding unnecessary complexity.

To use it, you define an interface which represents the endpoint you wish to communicate with (more on that in a bit), where methods on that interface correspond to requests that can be made on it. RestEase will then generate an implementation of that interface for you, and by calling the methods you defined, the appropriate requests will be made. See Installation and Quick Start to get up and running!

Almost every aspect of RestEase can be overridden and customized, leading to a large level of flexibility.

It also works on platforms which don't support runtime code generation, such as .NET Native and iOS, if you reference RestEase.SourceGenerator. See Using RestEase.SourceGenerator for more information.

RestEase is built on top of HttpClient and is deliberately a "leaky abstraction": it is easy to gain access to the full capabilities of HttpClient, giving you control and flexibility, when you need it.

RestEase is inspired by Anaïs Betts' Refit, which in turn is inspired by Retrofit.

Table of Contents

1. Installation
2. Quick Start
3. Request Types
4. Return Types
5. Query Parameters
   1. Constant Query Parameters
   2. Variable Query Parameters
      1. Formatting Variable Query Parameters
      2. Serialization of Variable Query Parameters
   3. Query Parameters Map
   4. Raw Query String Parameters
   5. Query Properties
6. Paths
   1. Base Address
   2. Base Path
   3. Path Placeholders
      1. Path Parameters
         1. Formatting Path Parameters
         2. URL Encoding in Path Parameters
         3. Serialization of Path Parameters
      2. Path Properties
         1. Formatting Path Properties
         2. URL Encoding in Path Properties
         3. Serialization of Path Properties
7. Body Content
   1. URL Encoded Bodies
8. Response Status Codes
9. Cancelling Requests
10. Headers
    1. Constant Interface Headers
    2. Variable Interface Headers
       1. Formatting Variable Interface Headers
    3. Constant Method Headers
    4. Variable Method Headers
       1. Formatting Variable Method Headers
    5. Redefining Headers
11. Using RestEase.SourceGenerator
12. Using HttpClientFactory
13. Using RestEase with Polly
    1. Using Polly with RestClient
    2. Using Polly with HttpClientFactory
14. HttpClient and RestEase interface lifetimes
15. Controlling Serialization and Deserialization
    1. Custom JsonSerializerSettings
    2. Custom Serializers and Deserializers
       1. Deserializing responses: ResponseDeserializer
       2. Serializing request bodies: RequestBodySerializer
       3. Serializing request query parameters: RequestQueryParamSerializer
       4. Serializing request path parameters: RequestPathParamSerializer
       5. Controlling query string generation: QueryStringBuilder
16. Controlling the Requests
    1. RequestModifier
    2. Custom HttpClient
    3. Adding to HttpRequestMessage.Properties
17. Customizing RestEase
18. Interface Accessibility
19. Using Generic Interfaces
20. Using Generic Methods
21. Interface Inheritance
    1. Sharing common properties and methods
    2. IDisposable
22. Advanced Functionality Using Extension Methods
    1. Wrapping Other Methods
    2. Using IRequester Directly
23. FAQs

Installation

RestEase is available on NuGet. See that page for installation instructions.

If you're using C# 9 or .NET 5 (or higher), reference RestEase.SourceGenerator as well to get compile-time errors and faster execution. See Using RestEase.SourceGenerator for more information. If you're targetting iOS or .NET Native, you will need to do this, as runtime code generation isn't available.

If you're using ASP.NET Core, take a look at Using HttpClientFactory. For failure handling and retries using Polly, see Using RestEase with Polly.

Quick Start

To start, first create an public interface which represents the endpoint you wish to make requests to. Please note that it does have to be public, or you must add RestEase as a friend assembly, see Interface Accessibility below.

using System;
using System.Threading.Tasks;
using Newtonsoft.Json;
using RestEase;

namespace RestEaseSampleApplication
{
    // We receive a JSON response, so define a class to deserialize the json into
    public class User
    {
        public string Name { get; set; }
        public string Blog { get; set; }

        // This is deserialized using Json.NET, so use attributes as necessary
        [JsonProperty("created_at")]
        public DateTime CreatedAt { get; set; }
    }

    // Define an interface representing the API
    // GitHub requires a User-Agent header, so specify one
    [Header("User-Agent", "RestEase")]
    public interface IGitHubApi
    {
        // The [Get] attribute marks this method as a GET request
        // The "users" is a relative path the a base URL, which we'll provide later
        // "{userId}" is a placeholder in the URL: the value from the "userId" method parameter is used
        [Get("users/{userId}")]
        Task<User> GetUserAsync([Path] string userId);
    }

    public class Program
    {
        public static void Main(string[] args)
        {
            // Create an implementation of that interface
            // We'll pass in the base URL for the API
            IGitHubApi api = RestClient.For<IGitHubApi>("https://api.github.com");

            // Now we can simply call methods on it
            // Normally you'd await the request, but this is a console app
            User user = api.GetUserAsync("canton7").Result;
            Console.WriteLine($"Name: {user.Name}. Blog: {user.Blog}. CreatedAt: {user.CreatedAt}");
            Console.ReadLine();
        }
    }
}

Request Types

See the [Get("path")] attribute used above? That's how you mark that method as being a GET request. There are a number of other attributes you can use here - in fact, there's one for each type of request: [Get("path")], [Post("path")], [Put("path")], [Delete("path")], [Head("path")], [Options("path")], [Trace("path"))], [Patch("path")]. Use whichever one you need to.

The argument to [Get] (or [Post], or whatever) is typically a relative path, and will be relative to the base uri that you provide to RestClient.For<T>. (You can specify an absolute path here if you need to, in which case the base uri will be ignored). Also see the section on Paths.

Return Types

Your interface methods may return one of the following types:

• Task: This method does not return any data, but the task will complete when the request has completed
• Task<T> (where T is not one of the types listed below): This method will deserialize the response into an object of type T, using Json.NET (or a custom deserializer, see [Controlling Serialization and