https://github.com/twogood/activout.restclient
Create a REST(ish) API client only by defining the C# interface you want
https://github.com/twogood/activout.restclient
api csharp dotnet-core rest
Last synced: 4 months ago
JSON representation
Create a REST(ish) API client only by defining the C# interface you want
- Host: GitHub
- URL: https://github.com/twogood/activout.restclient
- Owner: twogood
- License: mit
- Created: 2018-07-14T13:10:56.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2026-02-16T19:29:54.000Z (5 months ago)
- Last Synced: 2026-02-20T00:28:07.081Z (5 months ago)
- Topics: api, csharp, dotnet-core, rest
- Language: C#
- Size: 400 KB
- Stars: 5
- Watchers: 0
- Forks: 2
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Activout Rest Client
Create a REST(ish) API client only by defining the C# interface you want.
*Shamelessly inspired by [Rest Client for MicroProfile](https://github.com/eclipse/microprofile-rest-client).*
## 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:
```C#
[Path("movies")]
[ErrorResponse(typeof(ErrorResponse))]
[Accept("application/json")]
[ContentType("application/json")]
public interface IMovieReviewService
{
Task> GetAllMovies();
Task> QueryMoviesByDate(
[QueryParam] DateTime begin,
[QueryParam] DateTime end);
[Get("/{movieId}/reviews")]
Task> GetAllReviews(string movieId);
[Get("/{movieId}/reviews/{reviewId}")]
Task GetReview(string movieId, string reviewId);
[Post("/{movieId}/reviews")]
Task SubmitReview(string movieId, Review review);
[Put("/{movieId}/reviews/{reviewId}")]
Task 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:
```C#
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();
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](https://github.com/twogood/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
```C#
public static IServiceCollection AddRestClient(this IServiceCollection self)
{
self.TryAddTransient();
self.TryAddTransient();
self.TryAddTransient();
self.TryAddTransient();
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` 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](https://github.com/maxpiva/Nancy.Rest.Client)
- [Rest.ServiceProxy](https://github.com/sirnewton01/Rest.ServiceProxy)
## Collaborate
This project is still under development - participation welcome!
## Related projects
- [Activout.DatabaseClient](https://github.com/twogood/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](http://activout.se) is a software company in Ronneby, Sweden.