Name: RestEase.HttpClientFactory
Author: Antony Male

RestEase.HttpClientFactory v1.6.1 — nugetz

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();
        }
    }
}

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

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

    // Is the same as:

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

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

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

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

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

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

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

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

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

    [Get("search")]
    Task<SearchResult> SearchAsync([Query("filter")] IEnumerable<string> filters);
}

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

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

public interface ISomeApi
{
    [Get("foo")]
    Task FooAsync([Query(null)] string nullParam, [Query("")] string emptyParam);
}

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

// Requests https://api.example.com/foo?onitsown&=nokey
await api.FooAsync("onitsown", "nokey");

public interface ISomeApi
{
    [Get("path")]
    Task FooAsync([Query] string foo, [Query] string bar);
}

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

// Requests https://api.example.com/path?bar=
await api.FooAsync(null, "");

public interface ISomeApi
{
    [Get("foo")]
    Task FooAsync([Query(Format = "X2")] int param);
}

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

// Requests https://api.example.com/foo?param=FE
await api.FooAsync(254);

public class SearchParams
{
    public string Term { get; set; }
    public string Mode { get; set; }
}

public interface ISomeApi
{
    [Get("search")]
    Task<SearchResult> SearchAsync([Query(QuerySerializationMethod.Serialized)] SearchParams param);
}

ISomeApi api = RestClient.For<ISomeApi>("https://api.example.com");
// Requests https://api.example.com/search?params={"Term": "foo", "Mode": "basic"}
await api.SearchAsync(new SearchParams() { Term = "foo", Mode = "basic" });

[SerializationMethods(Query = QuerySerializationMethod.Serialized)]
public interface ISomeApi
{
    [Get("search")]
    [SerializationMethods(Query = QuerySerializationMethod.ToString)]
    Task<SearchResult> SearchWithToStringAsync([Query] SearchParams param);

    [Get("search")]
    Task<SearchResult> SearchWithSerializedAsync([Query] SearchParams param);
}

public interface ISomeApi
{
    [Get("search")]
    // I've used IDictionary<string, string[]> here, but you can use whatever type parameters you like,
    // or any type which implements IDictionary<TKey, TValue>
    Task<SearchResult> SearchBlogPostsAsync([QueryMap] IDictionary<string, string[]> filters);
}

var api = RestClient.For<ISomeApi>("https://api.example.com");
var filters = new Dictionary<string, string[]>()
{
    { "title", new[] { "bobby" } },
    { "tag", new[] { "c#", "programming" } }
};

// Requests https://api.example.com/search?title=bobby&tag=c%23&tag=programming
var searchResults = await api.SearchBlogPostsAsync(filters);

public interface ISomeApi
{
    [Get("search")]
    Task<SearchResult> SearchAsync([RawQueryString] string customFilter);
}

var api = RestClient.For<ISomeApi>("https://api.example.com");
var filter = "filter=foo";
// Requests https://api.example.com?filter=foo
var searchResults = await api.SearchAsync(filter);

public interface ISomeApi
{
	[Query("foo")]
	string Foo { get; set; }

	[Get("thing")]
	Task ThingAsync([Query] string foo);
}

var api = RestClient.For<ISomeApi>("https://api.example.com");
api.Foo = "bar";

// Requests https://api.example.com?foo=baz&foo=bar
await api.ThingAsync("baz");

public interface ISomeApi
{
    [Get("user/{userId}")]
    Task<User> FetchUserAsync([Path] string userId);
}

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

// Requests https://api.example.com/user/fred
await api.FetchUserAsync("fred");

public interface ISomeApi
{
    [Get("user/{userId}")]
    Task<User> FetchUserAsync([Path("userId")] string idOfTheUser);
}

public interface ISomeApi
{
    [Get("foo/{bar}")]
    Task FooAsync([Path("bar", Format = "D2")] int param);
}

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

// Requests https://api.example.com/foo/01
await api.FooAsync(1);

public interface ISomeApi
{
    [Get("foo/{bar}")]
    Task FooAsync([Path(UrlEncode = false)] string bar);
}

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

// Requests https://api.example.com/foo/bar/baz
await api.FooAsync("bar/baz");

{
    "Second": "/v1/second"
}

[BasePath("v1")]
public interface ISomeApi
{
    [Get("first")]
    Task<FirstResponse> GetFirstAsync();

    [Get("{url}")]
    Task GetSecondAsync([Path] string url);
}

ISomeApi api = RestClient.For<ISomeApi>("https://api.example.com");
var response = await api.GetFirstAsync();
await api.GetSecondAsync(response.Second);

public enum MyEnum
{
    [Display(Name = "first")]
    First,

    [Display(Name = "second")]
    Second,
}

public interface ISomeApi
{
    [Get("path/{param}")]
    Task<string> GetAsync([Path(PathSerializationMethod.Serialized)] MyEnum param);
}

ISomeApi api = new RestClient()
{
    RequestPathParamSerializer = new StringEnumRequestPathParamSerializer()
}.For<ISomeApi>("https://api.example.com");

// Requests https://api.example.com/path/first
await api.GetAsync(MyEnum.First);

[SerializationMethods(Path = PathSerializationMethod.Serialized)]
public interface ISomeApi
{
    [Get("path/{foo}")]
    [SerializationMethods(Path = PathSerializationMethod.ToString)]
    Task<string> GetWithToStringAsync([Path] MyEnum foo);

    [Get("path/{foo}")]
    Task<string> GetWithSerializedAsync([Path] MyEnum foo);
}

public interface ISomeApi
{
    [Path("accountId")]
    int AccountId { get; set; }

    [Get("{accountId}/profile")]
    Task<Profile> GetProfileAsync();

    [Delete("{accountId}")]
    Task DeleteAsync([Path("accountId")] int accountId);
}

var api = RestClient.For<ISomeApi>("https://api.example.com/user");
api.AccountId = 3;

// Requests https://api.example.com/user/3/profile
var profile = await api.GetProfileAsync();

// Requests https://api.example.com/user/4/profile
await api.DeleteAsync(4);

public interface ISomeApi
{
    [Path("accountId", Format = "N")]
    Guid AccountId { get; set; }

    [Get("{accountId}/profile")]
    Task<Profile> GetProfileAsync();
}

var api = RestClient.For<ISomeApi>("https://api.example.com/user");
api.AccountId = someGuid;

// Requests e.g. /user/00000000000000000000000000000000 /profile
var profile = await api.GetProfileAsync();

public interface ISomeApi
{
    [Path("pathPart", UrlEncode = false)]
    Guid PathPart { get; set; }

    [Get("{pathPart}/profile")]
    Task GetAsync();
}

var api = RestClient.For<ISomeApi>("https://api.example.com");
api.PathPart = "users/abc";

// Requests https://api.example.com/users/abc/profile
await api.GetAsync();

public enum MyEnum
{
    [Display(Name = "first")]
    First,

    [Display(Name = "second")]
    Second,
}

public interface ISomeApi
{
    [Path("pathPart", PathSerializationMethod.Serialized)]
    MyEnum PathPart { get; set; }

    [Get("path/{pathPart}")]
    Task<string> GetAsync();
}

ISomeApi api = new RestClient()
{
    RequestPathParamSerializer = new StringEnumRequestPathParamSerializer()
}.For<ISomeApi>("https://api.example.com");

api.PathPart = MyEnumSecond;
// Requests https://api.example.com/path/second
await api.GetAsync();

public interface ISomeApi
{
    [Post("users/new")]
    Task CreateUserAsync([Body] User user);
}

public interface IMeasurementProtocolApi
{
    [Post("collect")]
    Task CollectAsync([Body(BodySerializationMethod.UrlEncoded)] Dictionary<string, object> data);
}

var data = new Dictionary<string, object> {
    {"v", 1},
    {"tids", new[] { "UA-1234-5", "UA-1234-6" },
    {"cid", new Guid("d1e9ea6b-2e8b-4699-93e0-0bcbd26c206c")},
    {"t", "event"},
};

// Serialized as: v=1&tids=UA-1234-5&tids=UA-1234-6&cid=d1e9ea6b-2e8b-4699-93e0-0bcbd26c206c&t=event
await api.CollectAsync(data);

[SerializationMethods(Body = BodySerializationMethod.UrlEncoded)]
public interface ISomeApi
{
    [Post("collect")]
    Task CollectAsync([Body] Dictionary<string, object> data);
}

try
{
    var response = await client.SayHelloAsync();
}
catch (ApiException e) when (e.StatusCode == HttpStatusCode.NotFound)
{
    var notFoundResponse = e.DeserializeContent<NotFoundRepsonse>();
    // ...
}

public interface ISomeApi
{
    [Get("users/{userId}")]
    [AllowAnyStatusCode]
    Task<Response<User>> FetchUserThatMayNotExistAsync([Path] int userId);
}

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

using (var response = await api.FetchUserThatMayNotExistAsync(3));
if (response.ResponseMessage.StatusCode == HttpStatusCode.NotFound)
{
    // User wasn't found
}
else
{
    var user = response.GetContent();
    // ...
}

public interface ISomeApi
{
    [Get("very-large-response")]
    Task<LargeResponse> GetVeryLargeResponseAsync(CancellationToken cancellationToken);
}

[Header("User-Agent", "RestEase")]
[Header("Cache-Control", "no-cache")]
public interface IGitHubApi
{
    [Get("users")]
    Task<List<User>> GetUsersAsync();
}

public interface ISomeApi
{
    [Header("X-API-Key")]
    string ApiKey { get; set; }

    [Get("users/{userId}")]
    Task<User> FetchUserId([Path] string userId);
}

ISomeApi api = RestClient.For<ISomeApi>("https://api.example.com")
api.ApiKey = "The-API-KEY-value";
// ...

public interface ISomeApi
{
    [Header("X-API-Key", "None")]
    string ApiKey { get; set; }

    [Get("users/{userId}")]
    Task<User> FetchUserAsync([Path] string userId);
}

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

// "X-API-Key: None"
var user = await api.FetchUserAsync("bob");

public interface ISomeApi
{
    [Header("SomeHeader", Format = "X2")]
    int SomeHeader { get; set; }

    [Get("foo")]
    Task FooAsync();
}

ISomeApi api = RestClient.For<ISomeApi>("https://api.example.com");
api.SomeHeader = 254;
// SomeHeader: FE
await api.FooAsync();

public interface IGitHubApi
{
    [Header("User-Agent", "RestEase")]
    [Header("Cache-Control", "no-cache")]
    [Get("users")]
    Task<List<User>> GetUsersAsync();

    // This method doesn't have any headers applied
    [Get("users/{userId}")]
    Task<User> GetUserAsync([Path] string userId);
}

public interface ISomeApi
{
    [Get("users")]
    Task<List<User>> GetUsersAsync([Header("Authorization")] string authorization);
}

public interface ISomeApi
{
    [Get("foo")]
    Task FooAsync([Header("SomeHeader", Format = "X2")] int someHeader);
}

ISomeApi api = RestClient.For<ISomeApi>("https://api.example.com");
// SomeHeader: FE
await api.FooAsync(254);

[Header("X-InterfaceOnly", "InterfaceValue")]
[Header("X-InterfaceAndParamater", "InterfaceValue")]
[Header("X-InterfaceAndMethod", "InterfaceValue"]
[Header("X-InterfaceAndParameter", "InterfaceValue"]
[Header("X-InterfaceAndMethod-ToBeRemoved", "InterfaceValue")]
public interface ISomeApi
{
    [Header("X-ParameterOnly")]
    string ParameterOnlyHeader { get; set; }

    [Header("X-InterfaceAndParameter")]
    string InterfaceAndParameterHeader { get; set; }

    [Header("X-ParameterAndMethod")]
    string ParameterAndMethodHeader { get; set; }

    [Get("url")]
    [Header("X-MethodOnly", "MethodValue")]
    [Header("X-MethodAndParameter", "MethodValue")]
    [Header("X-ParameterAndMethod", "MethodValue")]
    [Header("X-InterfaceAndMethod-ToBeRemoved", null)]
    Task DoSomethingAsync(
        [Header("X-ParameterOnly")] string parameterOnly,
        [Header("X-MethodAndParameter")] string methodAndParameter,
        [Header("X-InterfaceAndParameter")] string interfaceAndParameter
    );
}

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

api.ParameterOnlyHeader = "ParameterValue";
api.InterfaceAndParameterHeader = "ParameterValue";
api.ParameterAndMethodHeader = "ParameterValue";

await api.DoSomethingAsync("ParameterValue", "ParameterValue", "ParameterValue");

// Has the following headers:
// X-InterfaceOnly: InterfaceValue
// X-InterfaceAndParameter: InterfaceValue, ParameterValue
// X-InterfaceAndMethod: MethodValue
// X-InterfaceAndParameter: ParameterValue

// X-ParameterAndMethod: MethodValue

// X-MethodOnly: MethodValue
// X-MethodAndParameter: MethodValue, ParameterValue

// X-ParameterAndMethod-ToBeRemoved isn't set, because it was removed

services.AddRestEaseClient<ISomeApi>("https://api.example.com");

services.AddRestEaseClient<ISomeApi>("https://api.example.com", new()
{
    RestClientConfigurer = client => client.RequestPathParamSerializer = new StringEnumRequestPathParamSerializer(),
});

services.AddRestEaseClient<ISomeApi>("https://api.example.com", new()
{
    InstanceConfigurer = instance => instance.SomeHeader = "Some Value",
});

services.AddRestEaseClient<ISomeApi>("https://api.example.com")
    .AddHttpMessageHandler<SomeHandler>()
    .SetHandlerLifetime(TimeSpan.FromMinutes(2));

public class SomeController : ControllerBase
{
    private readonly ISomeApi someApi;
    public SomeController(ISomeApi someApi) => this.someApi = someApi;
}

services.AddHttpClient("example")
    .ConfigureHttpClient(x => x.BaseAddress = new Uri("https://api.example.com"))
    .UseWithRestEaseClient<ISomeApi>()
    .UseWithRestEaseClient<ISomeOtherApi>();

// Define your policy however you want
var policy = Policy
    .HandleResult<HttpResponseMessage>(r => r.StatusCode == HttpStatusCode.NotFound)
    .RetryAsync();

// Tell RestEase to use it
var api = RestClient.For<ISomeApi>("https://api.example.com", new PolicyHttpMessageHandler(policy));
// ... or ...
var api = new RestClient("https://api.example.com", new PolicyHttpMessageHandler(policy)).For<ISomeApi>();

// Define your policy however you want
var policy = Policy
    .HandleResult<HttpResponseMessage>(r => r.StatusCode == HttpStatusCode.NotFound)
    .RetryAsync();

services.AddRestEaseClient<ISomeApi>("https://api.example.com").AddPolicyHandler(policy);

// ... or perhaps ...

services
    .AddRestEaseClient<ISomeApi>("https://api.example.com")
    .AddTransientHttpErrorPolicy(builder => builder.WaitAndRetryAsync(new[]
    {
        TimeSpan.FromSeconds(1),
        TimeSpan.FromSeconds(5),
        TimeSpan.FromSeconds(10)
    }));

var settings = new JsonSerializerSettings()
{
    ContractResolver = new CamelCasePropertyNamesContractResolver(),
    Converters = { new StringEnumConverter() }
};

var api = new RestClient("https://api.example.com")
{
    JsonSerializerSettings = settings
}.For<ISomeApi>();

// This API returns XML

public class XmlResponseDeserializer : ResponseDeserializer
{
    public override T Deserialize<T>(string content, HttpResponseMessage response, ResponseDeserializerInfo info)
    {
        // Consider caching generated XmlSerializers
        var serializer = new XmlSerializer(typeof(T));

        using (var stringReader = new StringReader(content))
        {
            return (T)serializer.Deserialize(stringReader);
        }
    }
}

// ...

var api = new RestClient("https://api.example.com")
{
    ResponseDeserializer = new XmlResponseDeserializer()
}.For<ISomeApi>();

public class XmlRequestBodySerializer : RequestBodySerializer
{
    public override HttpContent SerializeBody<T>(T body, RequestBodySerializerInfo info)
    {
        if (body == null)
            return null;

        // Consider caching generated XmlSerializers
        var serializer = new XmlSerializer(typeof(T));

        using (var stringWriter = new StringWriter())
        {
            serializer.Serialize(stringWriter, body);
            var content = new StringContent(stringWriter.ToString());
            // Set the default Content-Type header to application/xml
            content.Headers.ContentType.MediaType = "application/xml";
            return content;
        }
    }
}

// ...

var api = new RestClient("https://api.example.com")
{
    RequestBodySerializer = new XmlRequestBodySerializer()
}.For<ISomeApi>();

return new[]
{
    new KeyValuePair<string, string>("foo", "bar"),
    new KeyValuePair<string, string>("foo", "baz"),
    new KeyValuePair<string, string>("yay", "woo")
}

// Will get serialized to '...?foo=bar&foo=baz&yay=woo'

// It's highly unlikely that you'll get an API which requires xml-encoded query
// parameters, but for the sake of an example:

public class XmlRequestQueryParamSerializer : RequestQueryParamSerializer
{
    public override IEnumerable<KeyValuePair<string, string>> SerializeQueryParam<T>(string name, T value, RequestQueryParamSerializerInfo info)
    {
        if (value == null)
            yield break;

        // Consider caching generated XmlSerializers
        var serializer = new XmlSerializer(typeof(T));

        using (var stringWriter = new StringWriter())
        {
            serializer.Serialize(stringWriter, value);
            yield return new KeyValuePair<string, string>(name, stringWriter.ToString()));
        }
    }

    public override IEnumerable<KeyValuePair<string, string>> SerializeQueryCollectionParam<T>(string name, IEnumerable<T> values, RequestQueryParamSerializerInfo info)
    {
        if (values == null)
            yield break;

        // Consider caching generated XmlSerializers
        var serializer = new XmlSerializer(typeof(T));

        foreach (var value in values)
        {
            if (value != null)
            {
                using (var stringWriter = new StringWriter())
                {
                    serializer.Serialize(stringWriter, value);
                    yield return new KeyValuePair<string, string>(name, stringWriter.ToString()));
                }
            }
        }
    }
}

var api = new RestClient("https://api.example.com")
{
    RequestQueryParamSerializer = new XmlRequestQueryParamSerializer()
}.For<ISomeApi>();

var api = new RestClient("https://api.example.com")
{
    RequestPathParamSerializer = new StringEnumRequestPathParamSerializer(),
}.For<ISomeApi>();

public interface IMyRestService
{
    [Get("getPublicInfo")]
    Task<Foobar> SomePublicMethodAsync();

    [Get("secretStuff")]
    [Header("Authorization", "Bearer")]
    Task<Location> GetLocationOfRebelBaseAsync();
}

AuthenticationContext context = new AuthenticationContext(...);
IGitHubApi api = RestClient.For<IGitHubApi>("http://api.github.com", async (request, cancellationToken) =>
{
    // See if the request has an authorize header
    var auth = request.Headers.Authorization;
    if (auth != null)
    {
        // The AquireTokenAsync call will prompt with a UI if necessary
        // Or otherwise silently use a refresh token to return a valid access token
        var token = await context.AcquireTokenAsync("http://my.service.uri/app", "clientId", new Uri("callback://complete")).ConfigureAwait(false);
        request.Headers.Authorization = new AuthenticationHeaderValue(auth.Scheme, token);
  }
});

public class CustomHttpClientHandler : WebRequestHandler
{
    // Let's log all of our requests!
    private static readonly Logger logger = LogManager.GetCurrentClassLogger();

    public CustomHttpClientHandler()
    {
        // Allow any cert, valid or invalid
        this.ServerCertificateValidationCallback = (sender, certificate, chain, sslPolicyErrors) => true;
    }

    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        if (logger.IsTraceEnabled)
        {
            var response = await base.SendAsync(request, cancellationToken);
            logger.Trace((await response.Content.ReadAsStringAsync()).Trim());
            return response;
        }
        else
        {
            return await base.SendAsync(request, cancellationToken);
        }
    }
}

var httpClient = new HttpClient(new CustomHttpClientHandler())
{
    BaseAddress = new Uri("https://secure-api.example.com"),
    Timeout = TimeSpan.FromSeconds(3), // Very slow to respond, this server
};

ISomeApi api = RestClient.For<ISomeApi>(httpClient);

public interface ISomeApi
{
    [HttpRequestMessageProperty]
    CommonData AlwaysIncluded { get; set; }

    [Get]
    Task Get([HttpRequestMessageProperty("myKey")] string myValueIWantToAccessFromHttpMessageHandler);
}

protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
{
    var alwaysIncluded = (CommonData)request.Properties["AlwaysIncluded"];
    var myValueIWantToAccessFromHttpMessageHandler = (string)request.Properties["myKey"];

    // Let's use the properties!

    return await base.SendAsync(request, cancellationToken).ConfigureAwait(false);
}

public interface ISomeApi
{
    [Get("users/{userId}")]
    Task GetUserAsync([Path] string userId);
}

namespace RestEase.AutoGenerated
{
    public class ISomeApi
    {
        private readonly IRequester requester;

        public ISomeApi(IRequester requester)
        {
            this.requester = requester;
        }

        public Task GetUserAsync(string userId)
        {
            var requestInfo = new RequestInfo(HttpMethod.Get, "users/{userId}");
            requestInfo.AddPathParameter<string>("userId", userId);
            return this.requester.RequestVoidAsync(requestInfo);
        }
    }
}

[assembly: InternalsVisibleTo(RestEase.RestClient.FactoryAssemblyName)]

public interface IReallyExcitingCrudApi<T, TKey>
{
    [Post("")]
    Task<T> Create([Body] T paylod);

    [Get("")]
    Task<List<T>> ReadAll();

    [Get("{key}")]
    Task<T> ReadOne([Path] TKey key);

    [Put("{key}")]
    Task Update([Path] TKey key, [Body] T payload);

    [Delete("{key}")]
    Task Delete([Path] TKey key);
}

// The "/users" part here is kind of important if you want it to work for more
// than one type (unless you have a different domain for each type)
var api = RestClient.For<IReallyExcitingCrudApi<User, string>>("https://api.example.com/users");

public interface IReallyExcitingCrudApi
{
    [Post("")]
    Task<T> Create<T>([Body] T paylod);

    [Get("")]
    Task<List<T>> ReadAll<T>();

    [Get("{key}")]
    Task<T> ReadOne<T, TKey>(TKey key);

    [Put("{key}")]
    Task Update<T, TKey>(TKey key, [Body] T payload);

    [Delete("{key}")]
    Task Delete<TKey>(TKey key);
}

public interface IAuthenticatedEndpoint
{
    [Header("X-Api-Token")]
    string ApiToken { get; set; }

    [Header("X-Api-Username")]
    string ApiUsername { get; set; }

    [Path("userId")]
    int UserId { get; set; }
}

public interface IDevicesEndpoint : IAuthenticatedEndpoint
{
    [Get("/devices")]
    Task<IList<Device>> GetAllDevices([QueryMap] IDictionary<string, string> filters);
}

public interface IUsersEndpoint : IAuthenticatedEndpoint
{
    [Get("/user/{userId}")]
    Task<User> FetchUserAsync();
}

public interface ISomeApi
{
    // Method which is only used by SomeApiExtensions
    [Post("upload")]
    Task UploadAsync([Body] HttpContent content);
}

public static class SomeApiExtensions
{
    public static Task UploadAsync(this ISomeApi api, byte[] imageData, string token)
    {
        var content = new MultipartFormDataContent();

        var imageContent = new ByteArrayContent(imageData);
        imageContent.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg");
        content.Add(imageContent);

        var tokenContent = new FormUrlEncodedContent(new[]
        {
            new KeyValuePair<string, string>("token", token)
        });
        content.Add(tokenContent);

        return api.UploadAsync(content);
    }
}

public interface ISomeApi
{
    IRequester Requester { get; }
}

public static class SomeApiExtensions
{
    public static Task UploadAsync(this ISomeApi api, byte[] imageData, string token)
    {
        var content = new MultipartFormDataContent();

        var imageContent = new ByteArrayContent(imageData);
        imageContent.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg");
        content.Add(imageContent);

        var tokenContent = new FormUrlEncodedContent(new[]
        {
            new KeyValuePair<string, string>("token", token)
        });
        content.Add(tokenContent);

        var requestInfo = new RequestInfo(HttpMethod.Post, "upload");
        requestInfo.SetBodyParameterInfo(BodySerializationMethod.Default, content);
        return api.Requester.RequestVoidAsync(requestInfo);
    }
}

public interface ISomeApi
{
    [Header("Authorization")]
    AuthenticationHeaderValue Authorization { get; set; }

    [Get("foo")]
    Task DoSomethingAsync();
}

ISomeApi api = RestClient.For<ISomeApi>("https://api.example.com");
var value = Convert.ToBase64String(Encoding.ASCII.GetBytes("username:password1234"));
api.Authorization = new AuthenticationHeaderValue("Basic", value);

await api.DoSomethingAsync();

public interface ISomeApi
{
    [Get("users")]
    Task<UsersResponse> FetchUsersAsync();

    [Get("{url}")]
    Task<UsersResponse> FetchUsersByUrlAsync([Path(UrlEncode = false)] string url);
}

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

var firstPage = await api.FetchUsersAsync();
// Actually put decent logic here...
var secondPage = await api.FetchUsersByUrlAsync(firstPage.NextPage);

public class HybridResponseDeserializer : ResponseDeserializer
{
    private T DeserializeXml<T>(string content)
    {
        // Consider caching generated XmlSerializers
        var serializer = new XmlSerializer(typeof(T));

        using (var stringReader = new StringReader(content))
        {
            return (T)serializer.Deserialize(stringReader);
        }
    }

    private T DeserializeJson<T>(string content)
    {
        return JsonConvert.Deserialize<T>(content);
    }

    public override T Deserialize<T>(string content, HttpResponseMessage response)
    {
        switch (response.Content.Headers.ContentType.MediaType)
        {
            case "application/json":
                return this.DeserializeJson<T>(content);
            case "application/xml":
                return this.DeserializeXml<T>(content);
        }

        throw new ArgumentException("Response was not JSON or XML");
    }
}

var api = RestClient.For<ISomeApi>("https://api.example.com", new HybridResponseDeserializer());

public interface ISomeApi
{
    [Header("Content-Disposition", "form-data; filename=\"somefile.txt\"")]
    [Header("Content-Type", "text/plain")]
    [Post("upload")]
    Task UploadFileVersionOneAsync([Body] Stream file);

    [Post("upload")]
    // You can use strings instead of strongly-typed header values, if you want
    Task UploadFileVersionTwoAsync(
        [Header("Content-Disposition")] ContentDispositionHeaderValue contentDisposition,
        [Header("Content-Type")] MediaTypeHeaderValue contentType,
        [Body] Stream file);

    [Post("upload")]
    Task UploadFileVersionThreeAsync([Body] HttpContent content);
}

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

// Version one (constant headers)
using (var fileStream = File.OpenRead("somefile.txt"))
{
    await api.UploadFileVersionOneAsync(fileStream);
}

// Version two (variable headers)
using (var fileStream = File.OpenRead("somefile.txt"))
{
    var contentDisposition = new ContentDispositionHeaderValue("form-header") { FileName = "\"somefile.txt\"" };
    var contentType = new MediaTypeHeaderValue("text/plain");
    await api.UploadFileVersionTwoAsync(contentDisposition, contentType, fileStream);
}

// Version three (precise control over HttpContent)
using (var fileStream = File.OpenRead("somefile.txt"))
{
    var fileContent = new StreamContent(fileStream);
    fileContent.Headers.ContentDisposition = new ContentDispositionHeaderValue("form-header") { FileName = "\"somefile.txt\"" };
    fileContent.Headers.ContentType = new MediaTypeHeaderValue("text/plain");
    await api.UploadFileVersionThreeAsync(fileContent);
}

canton7/RestEase.HttpClientFactoryv1.6.1

Get Started

Readme

RestEase

Table of Contents

Installation

Quick Start

Request Types

Return Types

Query Parameters

Constant Query Parameters

Variable Query Parameters

Formatting Variable Query Parameters

Serialization of Variable Query Parameters

Query Parameters Map

Raw Query String Parameters

Query Properties

Paths

Base Address

Base Path

Path Placeholders

Path Parameters

Formatting Path Parameters

URL Encoding in Path Parameters

Serialization of Path Parameters

Path Properties

Formatting Path Properties

URL Encoding in Path Properties

Serialization of Path Properties

Body Content

URL Encoded Bodies

Response Status Codes

Cancelling Requests

Headers

Constant Interface Headers

Variable Interface Headers

Formatting Variable Interface Headers

Constant Method Headers

Variable Method Headers

Formatting Variable Method Headers

Redefining Headers

Using RestEase.SourceGenerator

Using HttpClientFactory

Using RestEase with Polly

Using Polly with RestClient

Using Polly with HttpClientFactory

HttpClient and RestEase interface lifetimes

Controlling Serialization and Deserialization

Custom JsonSerializerSettings

Custom Serializers and Deserializers

Deserializing responses: ResponseDeserializer

Serializing request bodies: RequestBodySerializer

Serializing request query parameters: RequestQueryParamSerializer

Serializing request path parameters: RequestPathParamSerializer

Controlling query string generation: QueryStringBuilder

Controlling the Requests

RequestModifier

Custom HttpClient

Adding to HttpRequestMessage.Properties

Customizing RestEase

Interface Accessibility

Using Generic Interfaces

Using Generic Methods

Interface Inheritance

Sharing common properties and methods

IDisposable

Advanced Functionality Using Extension Methods

Wrapping other methods

Using IRequester directly

FAQs

I want to use Basic Authentication

I need to request an absolute path

I may get responses in both XML and JSON, and want to deserialize both

Is RestEase thread safe?

I want to upload a file

I want to ensure that all of the required properties on my request body are set

Using Polly with `RestClient`

Custom `JsonSerializerSettings`

Deserializing responses: `ResponseDeserializer`

Serializing request bodies: `RequestBodySerializer`

Serializing request query parameters: `RequestQueryParamSerializer`

Serializing request path parameters: `RequestPathParamSerializer`

Controlling query string generation: `QueryStringBuilder`

`RequestModifier`

Custom `HttpClient`

Adding to `HttpRequestMessage.Properties`

Using `IRequester` directly