Skip to content
This repository has been archived by the owner. It is now read-only.
A simple .NET Core client library for interacting with REST services
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets
src/Deveel.Rest.Client
test/Deveel.Rest.Client.Tests
.gitignore
Deveel.Rest.sln
LICENSE
README.md
global.json

README.md

Build status MyGet NuGet

Deveel REST Client (DRest)

This is a simple .NET Core client library for interacting with REST services, making it easy to construct and invoke HTTP requests in a dynamic way.

Install the Library

Building a Client

To build a REST client with DRest is an easy process and it can be done with a straight constructor of RestClientSettings (or any class deriving from IRestClientSettings) or using a builder.

In this example, we will use a building strategy:

var client = RestClient.Build(settings => settings
                .BaseUri("http://api.example.com")
                .UseJsonSerializer()
                .UseDefaultHeader("X-DeviceId", "9999999999"));

The base URI of the service to contact is required in a building context, while when contructing the client using a reference to IHttpClient that value can be inferred from that low-level client.

By default, RestClientSettings includes all the default IContentSerializer instances defined by the library: if in the builder one or more specific serializers are specified to be used, the settings is cleared out by the default serializers and the explicitly specified are used.

Making a Request

The library provides the class RestRequest as the core element for constructing a REST request to a remote service: this includes parameters (Header, Route, QueryString, Body and File) and request-specific authentication.

It is also provided a building model for constructing requests dynamically

var request = RestRequest.Build(builder => builder
      .Get()
      .To("user/{userId}")
      .WithRoute("userId", 25)
      .Returns<User>());
      
var response = await client.RequestAsync(request);

var user = await response.GetBodyAsync<User>();

Extensions to the IRestClient provide utilities for building requests directly when sending the request.

var response = client.SendAsync(request => request
        .Post()
        .To("user/{userId}/setting")
        .WithRoute("userId", 101)
        .WithJsonBody(new UserSetting{Key="notify",Value=true})
        .WithHeader("X-Source", "iOS App"));

Content Serializers

The content (body) of a request or a response is serialized/deserialized by the client using implementations of IContentSerializer, selected by the analysis of the content type of a response or from an explicit specification of the request setup (either specifying the type of content posted or by using the default content defined in the client settings).

DRest defines some default implementations of the serializers

  • JsonContentSerializer: it is used to serialize datain or from JSON contents; it uses the Newtonsoft JSON.NET library as lower level serializer
  • XmlContentSerializer: handles requests and responses of XML formatted contents
  • KeyValueContentSerializer: although the www-form-urlencoded format is not explicitly recommended in REST model, this serializer is a utility when passing multi-parted content to a remote service (eg. additional data to an image file)

Authentication

Requests to a remote service can be optionally authenticated, given a strategy defined from implementations of IRequestAuthenticator: when specified, in the client settings or in the request settings, this is invoked before any request is sent to the remote service.

var client = RestClient.Build(builder => builder
      .BaseUri("http://api.example.com")
      .UseJwtAuthentication(token));
      
  ....
  
var response = client.SendAsync(request => request
      .Get()
      .To("token")
      .WithQueryString("grant_type", "password")
      .WithQueryString("username", "tester")
      .WithQueryString("password", "abc1234")
      .Authenticate(false));
      
var response2 = client.SendAsync(request => request
      .Get()
      .To("docs")
      .UseBasicAuthentication("developer", "dev1234")
      .Returns<dynamic>());

The request-level authenticator overrides any authentication configured at client-settings level, if any. It is also possible to request that a specific request is not authenticated: in this case none of the authenticators specified will be invoked.

You can’t perform that action at this time.