RESTFulSense 2.17.0

RESTFulSense

I designed & developed this library as a wrapper around the existing .NET Core HttpClient implementation to provide the following values:

1. Meaningful Exceptions for APIs response status codes.

2. Simplified API communications.

3. Test-friendly implementation.

You can get RESTFulSense Nuget package by typing:

Install-Package RESTFulSense

Here's the details of what this library has to offer:

1. Meaningful Exceptions

RESTFulSense provide the following exceptions for erroring HTTP Status Codes as follows:

2. Simplified API Communications

API controllers in ASP.NET Core today don't offer the full range of HTTP Codes that can be used to communicate certain events and errors to end users, in this library we managed to implement all the missing methods to communicate the full range of error codes as follows:

2.1 On Controller Level

This can be achieved by simply replacing the inheritance ControllerBase in your ASP.NET Core Controller class with RESTFulController as follows:

    [ApiController]
    [Route("api/[controller]")]
    public class ContactsController : RESTFulController
    {
        ...
    }

Once that's done, you will have full access to use any of the methods above to communicate more meaningful errors to your API consumers and clients.

2.2 On Consumer Level

Passing or retrieving objects from an API should be as simple as one method call, for RESTFulSense, you don't have to worry about how to serialize your input or deserialize the API output, here's how simple it works:

2.2.1 Initialization

The initialization of the RESTFulSense Client can be done in two different ways:

2.2.1.1 HttpClientFactory Approach

In your ASP.NET Core application, you can initialize the IRESTFulApiFactoryClient in your startup.cs as follows:

services.AddHttpClient<IRESTFulApiFactoryClient, RESTFulApiFactoryClient>(client => client.BaseAddress = new Uri(YOUR_API_URL));

2.2.1.2 Basic Initialization

You can also use the RESTFulClient simple initialize in a console app for instance as follows:

var apiClient = new RESTFulApiClient();

2.2.1 Deserialization

List<Student> students = 
    await restfulApiClient.GetContentAsync<List<Student>>(relativeUrl: "api/students");

2.2.2 Serialization

Student student = 
    await restfulApiClient.PostContentAsync<Student>(relativeUrl: "api/students", content: inputStudent); 

In addition to the wrappers around API calls and serialization/deserialization, this library also provides a simplified way to execute communications without any workarounds.

For instance, to execute a PUT API call without a body, to update a status for instance, you don't have to fake a PUT body to execute a successful call, you can just do the follows:

Account activatedAccount = 
    await restfulApiClient.PutContentAsync(relativeUrl: $"api/accounts/{accountId}/activate");

3. MultipartFormDataContent support

RESTFulSense allows you to easily convert a C# class with attributes into a MultipartFormDataContent and send it as a POST request using the PostFormAsync method.

The library includes the following attributes:

These attributes allow you to specify the content types and names of the form data. The RESTFulFileNameAttribute also allows you to add a file name to the content. Simply apply the attributes to your class properties and the library will handle the rest.

Here's an example usage:

public class FormUpload
{
    [RESTFulStreamContent(name: "file")]
    public Stream Stream { get; set; }

    [RESTFulStringContent(name: "purpose")]
    public string Purpose { get; set; }

    [RESTFulFileName(name: "file")]
    public string FileName { get; set; }
}

// ...

var formUpload = new FormUpload
{
    Stream = GetStream(),
    Purpose = "fine-tune",
    FileName = "SomeFile.jsonl"
};

var result = await PostFormAsync<FormUpload, ResultType>("https://example.com/upload", formUpload);

Note the linking of the FileName to the StreamContent via the name parameter in the attributes.

4. Testing-Friendly Implementation

RESTFulSense provides an interface to the API client class, to make it easier to mock and leverage dependency injection for the testability of the client consumers, here's an example:

var restfulApiClientMock = new Mock<IRestfulApiClient>();

restfulApiClient.Setup(client =>
    client.GetContentAsync<Student>(relativeUrl: $"api/students/{studentId}")
        .ReturnsAsync(student);

If you have any suggestions, comments or questions, please feel free to contact me on:

Twitter

LinkedIn

E-Mail

Huge thanks to Mr. Brian Parker @BrianLParker for his RESTfulSense Web Assembly effort.