Awesome
RestLess
RestLess is another type-safe REST API client library. It is heavily inspired by Refit, which is inspired by Retrofit, but does not works exactly the same way.
In fact RestLess is built by keeping in mind that reflection is slow. When we build beautiful apps we don't want them to be slow down because of an external library, that's why all the RestLess REST clients are fully generated during the compilation.
This library fully supports the uri template defined by the RFC6570 thanks to DoLess.UriTemplates.
Performance comparison
The main goal of RestLess is to be fast. So I created a little benchmark project that can be run on Android. I benchmarked Refit against RestLess for now, on two devices (time is in ms):
Device 1
This is an old device running under Android 4.4.
Device 2
Samsung 2017 flagship runnind under Android 7.0.
Conclusion
RestLess is really fast, especially at startup time. On an old device, with Refit, the startup time is more than one second while RestLess is 9 times faster with 120ms! On the request time side, RestLess is faster thant Refit, but I don't think this is very relevant since the network will be the bottleneck.
How it works
Install the NuGet package called RestLess and one of the extra package (like RestLess.JsonNet) into your project. A RestLess folder with a file named RestClient.g.dl.rest.cs will be inserted in your project. This file will allow you to create the Rest client from your interface without reflection.
As in Refit, you have to create an interface representing your REST API and use attributes to indicate what to do. During the project compilation, all REST clients will be generated.
Warning: In Visual Studio for Mac, with versions prior to 0.7.1, the intellisense does not detect RestClient
, but it will compile nonetheless.
From 0.7.1, you will have to close Visual Studio for Mac after adding this package and open it again. This is because Visual Studio for Mac keeps some project properties in cache.
Install
Available on NuGet.
Install RestLess
Install RestLess.JsonNet if you want to serialize/deserialize using Json.Net
Quick start
1°) Create your REST API interface
[Header("User-Agent", "RestLess")]
public interface IGitHubApi
{
[Get("users{/userId}")]
Task<User> GetUserAsync(string userId);
}
2°) Get the actual REST client
IGitHubApi gitHubApi = RestClient.For<IGitHubApi>("https://api.github.com");
3°) Make the call
User user = await gitHubApi.GetUserAsync("lestar");
REST client customization
You can change the way the API works with two things: The HttpClient
that can be passed to the For
method, or with the RestSettings
HttpClient
The For
method accepts a HttpClient
, so you can initialize it with a HttpMessageHandler
.
With this, you can set default headers with a runtime value that will be the same accross all calls. You can also create a DelegatingHandler
for authentification, an other one for logging, etc.
RestSettings
These settings are used directly by the requests generated by RestLess.
You can set custom parameters or formatters but the default RestSettings
does not come with useful formatters (Because we don't want the core package to have a lot of dependencies).
For example, if you want to serialize/deserialize JSON content with Json.Net you'll have to get the RestLess.JsonNet NuGet package. Of course, you can write your own, if what you are looking for does not yet exists.
Custom parameters
Custom parameters can be set at runtime but they are common to the entire REST client. These parameters can be used inside HeaderAttributes
(set the isCustomParameter
parameter to true) or inside the uri templates defined into the HTTP Method attributes
settings.CustomParameters.Add("api_key", "bXlhcGlrZXk=");
Formatters
The formatters can change the way an object is serialized/deserialized. There must be a default formatter for each kind of formatter.
As opposed to Refit you can use a specific formatter for a method and use the default one for the others.
MediaTypeFormatters
These formatters are used to serialize/deserialize the body of a HTTP request/response from/into an object.
You can set a method-specific MediaTypeFormatter like this:
RestSettings restSettings = new RestSettings();
restSettings.MediaTypeFormatters.Set("MediaTypeJsonFormatter", new MyMediaTypeJsonFormatter());
...
[Get("/whatever")]
[MediaTypeFormatter("MediaTypeJsonFormatter")]
Task<HttpResponseMessage> GetAsync();
UrlParameterFormatters
These formatters are used to serialize an object into a string. This string will be used to expand the variable in the uri template.
You can set a method-specific UrlParameterFormatter like this:
RestSettings restSettings = new RestSettings();
restSettings.UrlParameterFormatters.Set("UrlParameterFormatter", new MyUrlParameterFormatter());
...
[Get("/whatever{?obj}")]
[UrlParameterFormatter("UrlParameterFormatter")]
Task<HttpResponseMessage> GetAsync(MyObject obj);
FormFormatters
These formatters are used to serialize an object into a IEnumerable<KeyValuePair<string,string>>
that will be used to create an encoded url form content.
You can set a method-specific FormFormatter like this:
RestSettings restSettings = new RestSettings();
restSettings.FormFormatters.Set("FormFormatter", new MyFormFormatterFormatter());
...
[Post("/whatever")]
[FormFormatter("FormFormatter")]
Task<HttpResponseMessage> PostAsync([FormUrlEncodedContent] MyObject obj);
Attributes
Setting the Http Method
In order to be identified as a REST interface, all methods of the interface must have a HTTP Method attribute that provides the request method and relative URL.
There are 8 built-in attributes: Delete, Get, Head, Options, Patch, Post, Put and Trace. The relative URL of the resource must be specified as the argument of this attribute and it have to respect the RFC6570 Uri template specification.
Note: You can use a literal string, or any expression (like a constant) as the attribute argument.
[Get("/users{/userId}")]
[Get("/users{?since}")]
A request URL can be updated dynamically with the values of the method parameters or through the CustomParameters of the RestSettings
class.
The parameter names are case-insensitive, so it will work correctly in this case:
[Get("/users{/userid}")]
Task<HttpResponseMessage> GetUserAsync(string userId);
You can use the Name
attribute to override the name of the parameter that will be used by the UriTemplate:
[Get("/users{/userId}")]
Task<HttpResponseMessage> GetUserAsync([Name("userId")] string id);
Setting global request uri prefix or suffix
If the REST API always starts with a common string, let's say a version number for example, you can put it into a UriTemplatePrefixAttribute
Alternatively you can do the same if you REST API always ends with the same string, using the UriTemplateSuffixAttribute
Setting headers
There are three ways to set a header value:
With a constant
If you have a header with a constant value you can use the HeaderAttribute
that way:
[Header("User-Agent", "AppAgentForAllMethods")]
public interface IRestApi
{
[Header("User-Agent", "AppAgentForThisMethodOnly")]
Task<User> GetUserAsync();
// .. Some code...
}
At runtime through the settings
You can also set a global header value at runtime for all the methods of your REST client:
RestSettings restSettings = new RestSettings();
restSettings.CustomParameters.Add("apiKey", ApiKey);
...
[Header("User-Agent", "apiKey", true)]
public interface IRestApi
{
// .. Some code...
}
Dynamically
If the content of the header can change between calls, you can apply a HeaderValueAttribute
to a parameter:
[Get("api/posts")]
Task<User> GetUserAsync([HeaderValue("User-Token")] string token);
Overwrite header values
Redefining a header will replace it in the following order of precedence:
Header
attribute on the interface (lowest priority)Header
attribute on the methodHeaderValue
attribute on a method parameter (highest priority)
Setting the body content
You can add a body content to your request by applying the Content
or the FormUrlEncodedContent
attribute to a method parameter.
With the Content
attribute, the parameter can have one the following types:
HttpContent
Stream
string
byte[]
object
=> This will use the specified MediaTypeFormatter (or the default one if not set)FileInfo
=> This trigger creates aMultipartFormDataContent
even if it is the only parameter
With the FormUrlEncodedContent
attribute, the parameter can have one the following types:
IEnumerable<KeyValuePair<string, string>>
object
=> This will use the specified FormFormatter (or the default one if not set)
You can decorate multiple parameters with the Content
or the FormUrlEncodedContent
attribute. The body of the request will be a MultipartFormDataContent
.
When you want to create a multipart request, the default name for each parameter will be the parameter name. You can ovveride this behavior with the Name
attribute.
You can also set an optional fileName or contentType through the attribute parameters.
Example:
[Post("api/posts")]
Task<HttpResponseMessage> PostMultipartContent03Async([Content]string content, [Name("firstName")][Content("f", "text/plain")]string content2);
Will create a content like this:
--RestLessBoundary
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=content
doe
--RestLessBoundary
Content-Type: text/plain
Content-Disposition: form-data; name=firstName; filename=f; filename*=utf-8''f
john
--RestLessBoundary--
Retrieving the response
All the REST client methods must return a Task
.
You can set a generic parameter type to the Task
, the valid ones are:
HttpResponseMessage
Stream
string
bool
=> This will return if the response has a success code without throwing an errorbyte[]
object
=> This will use the specified MediaTypeFormatter (or the default one if not set)
Get response header
Sometimes REST APIS return useful information in the headers of the response.
You can get them by setting the HeaderWriter
property of the RestSettings
:
public class HeaderWriter : IHeaderWriter
{
public void Write(HttpResponseHeaders headers, object obj)
{
if (obj is IPagedResponse pagedResponse)
{
if (headers.TryGetValue(PaginationPage, out int page))
{
pagedResponse.Page = page;
}
if (headers.TryGetValue(PaginationPageCount, out int pageCount))
{
pagedResponse.PageCount = pageCount;
}
}
}
}
...
mockHttp.Expect(HttpMethod.Get, url)
.Respond(x =>
{
var response = new HttpResponseMessage(HttpStatusCode.OK)
{
Content = new StringContent("[{'firstName':'A','lastName':'AA'},{'firstName':'B','lastName':'BB'}]", Encoding.UTF8, "application/json")
};
response.Headers.Add(PaginationPage, "1");
response.Headers.Add(PaginationPageCount, "2");
return response;
});
var settings = new JsonRestSettings()
{
HttpMessageHandlerFactory = () => mockHttp,
HeaderWriter = new HeaderWriter()
};
IApi09 restClient = RestClient.For<IApi09>(url, settings);
var people = await restClient.GetPagedPeopleAsync();
people.Page.ShouldBeEquivalentTo(1);
people.PageCount.ShouldBeEquivalentTo(2);
Differences with Refit
Unlike Refit, the core of RestLess does not use reflection at runtime (For MediaFormatters it depends of the implementation). All the REST methods are generated during compile-time.
The RestLess package does not have any dependencies to another third-party library (except DoLess.UriTemplates). In order to read/write Json, you need to reference RestLess.JsonNet for example, but you can also write your own formatting strategies.
RestLess supports:
- Generic methods
- Method polymorphism
- The use of constants inside the attributes
- UriTemplates: see the Spec
- Method specific formatters
- Getting response headers in the returned object
Not supported features
Right now, RestLess does not supports:
- Interface inheritance