Activout.RestClient 5.0.0

dotnet add package Activout.RestClient --version 5.0.0
                    
NuGet\Install-Package Activout.RestClient -Version 5.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Activout.RestClient" Version="5.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Activout.RestClient" Version="5.0.0" />
                    
Directory.Packages.props
<PackageReference Include="Activout.RestClient" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Activout.RestClient --version 5.0.0
                    
#r "nuget: Activout.RestClient, 5.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Activout.RestClient@5.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Activout.RestClient&version=5.0.0
                    
Install as a Cake Addin
#tool nuget:?package=Activout.RestClient&version=5.0.0
                    
Install as a Cake Tool

Activout Rest Client

Create a REST(ish) API client only by defining the C# interface you want.

Shamelessly inspired by Rest Client for MicroProfile.

Rationale

The Activout Rest Client provides a type-safe approach to invoke RESTful services over HTTP. As much as possible the Rest Client attempts to use .NET Core MVC APIs for consistency and easier re-use.

Example

Here is an example - let’s say that you want to use a movie review service. The remote service might provide APIs to view users' reviews and allow you to post and modify your own reviews. You might start with an interface to represent the remote service like this:

[Path("movies")]
[ErrorResponse(typeof(ErrorResponse))]
[Accept("application/json")]
[ContentType("application/json")]
public interface IMovieReviewService
{
    Task<List<Movie>> GetAllMovies();

    Task<List<Movie>> QueryMoviesByDate(
        [QueryParam] DateTime begin,
        [QueryParam] DateTime end);

    [Get("/{movieId}/reviews")]
    Task<IEnumerable<Review>> GetAllReviews(string movieId);

    [Get("/{movieId}/reviews/{reviewId}")]
    Task<Review> GetReview(string movieId, string reviewId);

    [Post("/{movieId}/reviews")]
    Task<Review> SubmitReview(string movieId, Review review);

    [Put("/{movieId}/reviews/{reviewId}")]
    Task<Review> UpdateReview(string movieId, string reviewId, Review review);

    [Post("/import.csv")]
    [ContentType("text/csv")]
    Task Import(string csv);
}

Now we can use this interface as a means to invoke the actual remote review service like this:

var restClientFactory = Services.CreateRestClientFactory();
var movieReviewService = restClientFactory
            .CreateBuilder()
            .With(_httpClient)
            .WithNewtonsoftJson() // or .WithSystemTextJson() for System.Text.Json
            .BaseUri(new Uri("https://example.com/movieReviewService"))
            .Build<IMovieReviewService>();

Review review = new Review(stars: 3, "This was a delightful comedy, but not terribly realistic.");
await movieReviewService.SubmitReview(movieId, review);

This allows for a much more natural coding style, and the underlying implementation handles the communication between the client and service - it makes the HTTP connection, serializes the Review object to JSON/etc. so that the remote service can process it.

External projects using Activout.RestClient

  • Activout.FuelPrice A console application that reads from Twitter of a specific chain of petrol stations to fetch my local fuel price.
  • Your project here?

Usage notes

  • Built for ASP.NET 8 and 9
  • Asynchronous calls (Task, Task<T>) are recommended. Synchronous calls are deprecated: a warning is logged when such a method is first used, and support will be removed in the next major version.
  • Additional serializers and deserializers can be added at will.
  • Support for custom error objects via [ErrorResponse] attribute. These will be included in a RestClientException that is thrown if the API call fails.

Usage with dependency injection through IServiceCollection

public static IServiceCollection AddRestClient(this IServiceCollection self)
{
  self.TryAddTransient<IParamConverterManager, ParamConverterManager>();
  self.TryAddTransient<IRestClientFactory, RestClientFactory>();
  return self;
}

JSON serialization support

Since version 5 Activout.RestClient does not depend on any specific JSON library. You must install either the Activout.RestClient.Newtonsoft.Json package (for Newtonsoft.Json support) or the Activout.RestClient.Json package ( for System.Text.Json support) to enable JSON serialization and deserialization.

Breaking changes in version 5

  • Replaced [JsonProperty] (JsonPropertyAttribute) in HTTP form data classes with [FormKey] (FormKeyAttribute) to avoid dependency on Newtonsoft.Json.
  • Extracted package Activout.RestClient.Newtonsoft.Json to make Activout.RestClient independent of Newtonsoft.Json.
  • Null values in HTTP form data, header and query parameters now means that no parameter is sent. To send a parameter without a value, an empty string must be used.
  • IDictionary and IDictionary<TKey, TValue> values for parameters annotated with [FormParam], [HeaderParam] or [QueryParam] are no longer serialized using IParamConverterManager but instead each key-value pair in the dictionary is sent as a separate parameter. Both key and value must be non-null values to be sent and IParamConverterManager will be used to convert each value to a string.
  • IParamConverter.CanConvert() signature changed to take both Type and ParameterInfo since the Type is different from the ParameterInfo.ParameterType for dictionary values.
  • Added a GetConverter(Type type) method to IParamConverterManager to get the converter for a type that is not ParameterInfo.

Breaking changes in version 3

  • Changed IRestClientBuilder.HttpClient() to a new overload of IRestClientBuilder.With()
  • Removed dependency on Microsoft.AspNetCore.Mvc.Core
    • Removed AddRestClient extension method on IServiceCollection, see Usage notes above
    • This means we now use our own attributes instead of those in Microsoft.AspNetCore.Mvc namespace:
      • [HttpGet] → [Get]
      • [HttpPost] → [Post]
      • [HttpPut] → [Put]
      • [HttpDelete] → [Delete]
      • [InterfaceRoute] → [Path]
      • [Route] → [Path]
      • [RouteParam] → [PathParam]
      • [InterfaceConsumes] and [Consumes] → [Accept] for setting Accept HTTP header or [ContentType] for POST/PUT data
      • Other attributes keep the same name but live in the Activout.RestClient namespace
    • This also meant replacing MediaTypeCollection and MediaType from Microsoft.AspNetCore.Mvc.Formatters namespace:
      • We have our own MediaType class now, which is just a value object
      • IDeserializer has a new method CanDeserialize and the SupportedMediaTypes property is removed. It also has a property
      • ISerializer has a new method CanSerialize and the SupportedMediaTypes property is removed
      • ISerializationManager method signatures changed accordingly

TODO

  • Support for cookie parameters, if someone need them

Comparison with Refit and Kiota

Refit and Kiota are the most common alternatives. An honest summary:

Activout.RestClient Refit Kiota
You write Attributed C# interface Attributed C# interface Nothing, generated from OpenAPI
Client created Runtime (DispatchProxy + reflection) Compile time (source generator) Generated code checked in
Trimming / NativeAOT No Yes with generated clients (reflection is opt-in via Refit.Reflection) Yes (libraries are IsAotCompatible)
Interface errors caught On first call Build time (analyzers and code fixes) N/A
IHttpClientFactory / DI Manual (pass an HttpClient) Refit.HttpClientFactory (AddRefitClient<T>()) Documented pattern: AddKiotaHandlers() plus your own client factory
Typed error bodies Declarative [ErrorResponse] ApiException.GetContentAsAsync<T>() Generated per status code from the OpenAPI spec, thrown as typed exceptions
Custom exception mapping IDomainExceptionMapperFactory ExceptionFactory in RefitSettings Only via the spec's error mappings
Serialization Pluggable per media type (System.Text.Json, Newtonsoft.Json, XML, text, ...) System.Text.Json (preferred), Newtonsoft.Json, XML JSON, form, multipart, text
Response wrapper HttpResponseMessage ApiResponse<T> NativeResponseHandler
Target frameworks .NET 8+ .NET 8–11, .NET Framework 4.6.2+ .NET Standard 2.0+
Languages C# C# C#, Go, Java, PHP, Python (stable); TypeScript, Dart, Ruby (preview)
Community Small Large Large (Microsoft)

Rule of thumb:

  • Large API with a good OpenAPI spec, or multiple languages: Kiota.
  • Hand-written client in a typical .NET app: Refit is the safe default, and the only choice of the three for trimmed or NativeAOT apps without an OpenAPI spec.
  • Activout.RestClient: if you prefer declaring typed error bodies with an attribute, want pluggable per-media-type serialization, and don't need trimming/AOT.

Similar projects

I deliberately implemented my project without even searching for C# projects using the same concept, but afterwards I have found these:

Collaborate

This project is still under development - participation welcome!

  • Activout.DatabaseClient - Create a database client only by defining methods on an interface and annotate them with SQL statements. Uses Dapper for object mapping.

About Activout

Activout AB is a software company in Ronneby, Sweden.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on Activout.RestClient:

Package Downloads
Activout.RestClient.Xml

XML Support for Activout.RestClient.

Activout.RestClient.Newtonsoft.Json

Newtonsoft.Json Support for Activout.RestClient.

Activout.RestClient.Json

System.Text.Json Support for Activout.RestClient.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
5.0.0 796 11/3/2026
5.0.0-beta5 202 2/26/2026
4.0.1 6,739 11/26/2024
4.0.0 193 11/26/2024
3.1.0 771 5/10/2022
3.0.5-beta 541 12/11/2020
3.0.4-beta2 514 12/7/2020
3.0.3 1,312 12/1/2020
Loading failed