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
• Both synchronous and asynchronous calls are supported. Asynchronous is recommended.
• 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<IDuckTyping, DuckTyping>();
  self.TryAddTransient<IParamConverterManager, ParamConverterManager>();
  self.TryAddTransient<IRestClientFactory, RestClientFactory>();
  self.TryAddTransient<ITaskConverterFactory, TaskConverter3Factory>();
  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

Similar projects

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

• Nancy.Rest.Client
• Rest.ServiceProxy

Collaborate

This project is still under development - participation welcome!

Related projects

• 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.