RestEase

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.

…

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. (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 (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 Deserialization below).
• Task: This method returns the raw response, as a string (although this can be customised, see here).
• Task: This method returns the raw HttpResponseMessage resulting from the request. It does not do any deserialiation. You must dispose this object after use.
• Task>: This method returns a Response. A Response contains both the deserialied response (of type T), but also the HttpResponseMessage. Use this when you want to have both the deserialized response, and access to things like the response headers. You must dispose this object after use.
• Task: This method returns a Stream containing the response. Use this to e.g. download a file and stream it to disk. You must dispose this object after use.

Non-async methods are not supported (use .Wait() or .Result as appropriate if you do want to make your request synchronous).

If you return a Task or a Task, then HttpCompletionOption.ResponseHeadersRead is used, so that you can choose whether or not the response body should be fetched (or report its download progress, etc). If however you return a Task, Task, or Task>, then HttpCompletionOption.ResponseContentRead is used, meaning that any CancellationToken that you pass will cancel the body download. If you return a Task, then the response body isn't fetched, unless an ApiException is thrown.

Query Parameters

It is very common to want to include query parameters in your request (e.g. /foo?key=value), and RestEase makes this easy.

Constant Query Parameters

The most basic type of query parameter is a constant - the value never changes. For these, simply put the query parameter as part of the URL:

public interface IGitHubApi
{
   [Get("users/list?sort=desc")]
   Task> GetUsersAsync();
}

Variable Query Parameters

Any parameters to a method which are:

• Decorated with the [Query] attribute, or
• Not decorated at all

will be interpreted as query parameters.

The name of the parameter will be used as the key, unless an argument is passed to [Query("key")], in which case that will be used instead.

For example:

public interface IGitHubApi
{
    [Get("user")]
    Task FetchUserAsync(int userid);

    // Is the same as:

    [Get("user")]
    Task FetchUserAsync([Query] int userid);

    // Is the same as:
    // (Note the casing of the parameter name)

    [Get("user")]
    Task FetchUserAsync([Query("userid")] int userId);
}

IGithubApi api = RestClient.For("http://api.github.com");

// Requests http://api.github.com/user?userid=3
await api.FetchUserAsync(3);

You can have duplicate keys if you want:

public interface ISomeApi
{
    [Get("search")]
    Task SearchAsync([Query("filter")] string filter1, [Query("filter")] string filter2);
}

ISomeApi api = RestClient.For("https://api.example.com");

// Requests http://somenedpoint.com/search?filter=foo&filter=bar
await api.SearchAsync("foo", "bar");

You can also have an array of query parameters:

public interface ISomeApi
{
    // You can use IEnumerable, or any type which implements IEnumerable

    [Get("search")]
    Task SearchAsync([Query("filter")] IEnumerable filters);
}

ISomeApi api = RestClient.For("https://api.example.com");

// Requests http://api.exapmle.com/search?filter=foo&filter=bar&filter=baz
await api.SearchAsync(new[] { "foo", "bar", "baz" });

If you specify a key that is null, i.e. [Query(null)], then the name of the key is not used, and the value is inserted into the query string. If you specify a key that is an empty string "", then then query key will be left empty.

public interface ISomeApi
{
    [Get("foo")]
    Task Fo