BeeQ.RestClient 1.2.0

BeeQ.RestClient

This library aims to facilitate REST calls in C# using the Fluent Interface and Builder Pattern.

Simple Example

The simplest and most direct usage is as follows:

public async Task<int> EasyUsage()
{
    var body = ...;

    await RestClient.Create()
        .UseBaseAddress("http://localhost:8080/")
        .SetBearerToken("...")
        .Build()
        .Post<int>("client", body);
}

• First, a new instance is requested using Create, a method to which the URL can be directly passed if desired.

• The URL is set.

• Authentication is configured if necessary.

• The RestClient object is built.

• Finally, the desired REST calls are made.

Recommended Usage

If you want to make multiple calls or preconfigure the REST client, you can do it like this:

public class MyService
{
    private readonly RestClient _client;

    public MyService() 
    {
        _client = RestClient.Create()
            .UseBaseAddress("http://localhost:8080/")
            .SetBearerToken("...")
            .Build();
    }

    public List<UserDto> GetUsers()
    {
        return _client.Get<List<UserDto>>("users/list");
    }
    
    public bool SaveUsers(UserDto dto)
    {
        return _client.Post<bool>("users", dto);
    }
}

Headers

The library currently features the 3 most popular authentication methods, as well as a custom mode for managing headers and authentication.

JWT / Bearer

Authentication via Bearer, better known as JWT, is the most common form of authentication in RESTful services.

RestClient.Create("http://localhost:8080/")
    .SetBearerToken("...")

Basic Auth

Although it is a less frequently used form of authentication, it is the simplest.

RestClient.Create("http://localhost:8080/")
    .SetBasicAuthorization("beeq", "1234")

API Key

The library also includes the option for API Key authentication—that is, a token sent in the request header via the X-Api-Key header.

RestClient.Create("http://localhost:8080/")
    .SetApiKey("sk_lkjl34kh5k3h4lkjh5r434f")

Timeout

You can set a timeout for requests:

RestClient.Create("http://localhost:8080/")
    .SetTimeout(TimeSpan.FromSeconds(5))

To reset the timeout, you can use the ResetTimeout() method.

RestClient

Once the RestClient is built, it can be used to execute various requests.

Currently, GET, POST, PUT, DELETE, and PATCH calls are supported. The functions feature Method Overloading, allowing you to use whichever best fits your needs.

Example of a GET request with dynamic parameters:

await RestClient.Create("http://localhost:8080/")
    .Build()
    .Get<List<UserDto>>("users/find", new { firstname = "john", lastname = null, status = "active" });

The example above will construct the URL http://localhost:8080/users/find?firstname=john&status=active.

Note that the lastname parameter is excluded since its value is null.

Automatic JWT Fetching

The library includes the ability to automatically fetch an access JWT for an API that requires keeping an updated JWT.

Simple example:

public async Task<UserDto?> GetUser(int id)
{
    var client = RestClient.Create("http://localhost:8080")
        .UseAutoRefreshJwt(async currentJwt =>
        {
            if (currentJwt == null)
                return await RestClient.Create("http://auth.service.com")
                    .Build()
                    .Post<string>("auth", new { user = "beeq", pass = "1234" }) ?? string.Empty;

            return await RestClient.Create("http://auth.service.com")
                .SetBearerToken(currentJwt)
                .Build()
                .Post<string>("auth/refresh-token", new { }) ?? string.Empty;
        })
        .Build();

    var userDto = await client.Get<UserDto>("user", new { Id = id });
    return userDto;
}

In this example, calling the UseAutoRefreshJwt function provides the current JWT, allowing you to use it to retrieve a new access token or renew it if necessary.

The token will automatically be set in the "Authorization" header under the "Bearer" scheme, which is the standard for JWT.

Custom Modifications per Call

The library allows modifying the HttpClient prior to each call via the RestClient's OnPreInvoke method, which returns the HttpClient object you wish to use for the call.

Appropriate precautions should be taken when using this Custom mode, as setting a new HttpClient will cause the system to use it and discard any previously established configuration. \

var client = RestClient.Create("http://localhost:8080")
    .Build()
    .OnPreInvoke(async http =>
    {
        http.BaseAddress = new Uri("http://api2.system.com");
        return await Task.FromResult(http);
    });

var userDto = await client.Get<UserDto>("user", new { Id = id });
return userDto;

In the example above, the base URL to be invoked is modified, and the updated HttpClient object is returned.