RESTFulSense 2.9.0

.NET Standard 2.1
dotnet add package RESTFulSense --version 2.9.0
NuGet\Install-Package RESTFulSense -Version 2.9.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="RESTFulSense" Version="2.9.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add RESTFulSense --version 2.9.0
#r "nuget: RESTFulSense, 2.9.0"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install RESTFulSense as a Cake Addin
#addin nuget:?package=RESTFulSense&version=2.9.0

// Install RESTFulSense as a Cake Tool
#tool nuget:?package=RESTFulSense&version=2.9.0

<p align="center"> <img width="25%" height="25%" src=""> </p>

.NET Nuget The Standard - COMPLIANT


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

<ol> <li>Meaningful Exceptions for APIs response status codes.</li> <li>Simplified API communications.</li> <li>Test-friendly implementation.</li> </ol>

<br />

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: <br />

Status Code Exception
BadRequest 400 HttpResponseBadRequestException
Unauthorized 401 HttpResponseUnauthorizedException
PaymentRequired 402 HttpResponsePaymentRequiredException
Forbidden 403 HttpResponseForbiddenException
NotFound 404 HttpResponseNotFoundException
NotFound 404 HttpResponseUrlNotFoundException
MethodNotAllowed 405 HttpResponseMethodNotAllowedException
NotAcceptable 406 HttpResponseNotAcceptableException
ProxyAuthenticationRequired 407 HttpResponseProxyAuthenticationRequiredException
RequestTimeout 408 HttpResponseRequestTimeoutException
Conflict 409 HttpResponseConflictException
Gone 410 HttpResponseGoneException
LengthRequired 411 HttpResponseLengthRequiredException
PreconditionFailed 412 HttpResponsePreconditionFailedException
RequestEntityTooLarge 413 HttpResponseRequestEntityTooLargeException
RequestUriTooLong 414 HttpResponseRequestUriTooLongException
UnsupportedMediaType 415 HttpResponseUnsupportedMediaTypeException
RequestedRangeNotSatisfiable 416 HttpResponseRequestedRangeNotSatisfiableException
ExpectationFailed 417 HttpResponseExpectationFailedException
MisdirectedRequest 421 HttpResponseMisdirectedRequestException
UnprocessableEntity 422 HttpResponseUnprocessableEntityException
Locked 423 HttpResponseLockedException
FailedDependency 424 HttpResponseFailedDependencyException
UpgradeRequired 426 HttpResponseUpgradeRequiredException
PreconditionRequired 428 HttpResponsePreconditionRequiredException
TooManyRequests 429 HttpResponseTooManyRequestsException
RequestHeaderFieldsTooLarge 431 HttpResponseRequestHeaderFieldsTooLargeException
UnavailableForLegalReasons 451 HttpResponseUnavailableForLegalReasonsException
InternalServerError 500 HttpResponseInternalServerErrorException
NotImplemented 501 HttpResponseNotImplementedException
BadGateway 502 HttpResponseBadGatewayException
ServiceUnavailable 503 HttpResponseServiceUnavailableException
GatewayTimeout 504 HttpResponseGatewayTimeoutException
HttpVersionNotSupported 505 HttpResponseHttpVersionNotSupportedException
VariantAlsoNegotiates 506 HttpResponseVariantAlsoNegotiatesException
InsufficientStorage 507 HttpResponseInsufficientStorageException
LoopDetected 508 HttpResponseLoopDetectedException
NotExtended 510 HttpResponseNotExtendedException
NetworkAuthenticationRequired 511 HttpResponseNetworkAuthenticationRequiredException

<br />

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: <br />

2.1 On Controller Level
Controller Method Code
PaymentRequired(object value) 402
MethodNotAllowed(object value) 405
NotAcceptable(object value) 406
ProxyAuthenticationRequired(object value) 407
RequestTimeout(object value) 408
Gone(object value) 410
LengthRequired(object value) 411
PreconditionFailed(object value) 412
RequestEntityTooLarge(object value) 413
RequestUriTooLong(object value) 414
UnsupportedMediaType(object value) 415
RequestedRangeNotSatisfiable(object value) 416
ExpectationFailed(object value) 417
MisdirectedRequest(object value) 421
UnprocessableEntity(object value) 422
Locked(object value) 423
FailedDependency(object value) 424
UpgradeRequired(object value) 426
PreconditionRequired(object value) 428
TooManyRequests(object value) 429
RequestHeaderFieldsTooLarge(object value) 431
UnavailableForLegalReasons(object value) 451
InternalServerError(object value) 500
NotImplemented(object value) 501
BadGateway(object value) 502
ServiceUnavailable(object value) 503
GatewayTimeout(object value) 504
HttpVersionNotSupported(object value) 505
VariantAlsoNegotiates(object value) 506
InsufficientStorage(object value) 507
LoopDetected(object value) 508
NotExtended(object value) 510
NetworkAuthenticationRequired(object value) 511

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

    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: 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));

<br /> Basic Initialization

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

var apiClient = new RESTFulApiClient();

<br />

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); 

<br />

In addition to the wrappers around API calls and serialization/deserialization, this library also provides a simplified way to execute communications without any workarounds. <br /> 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");

<br />

3. 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}")

<br />

If you have any suggestions, comments or questions, please feel free to contact me on: <br /> Twitter: @hassanrezkhabib <br /> LinkedIn: hassanrezkhabib <br /> E-Mail: <br />

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

Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows net7.0 net7.0-android net7.0-ios net7.0-maccatalyst net7.0-macos net7.0-tvos net7.0-windows
.NET Core netcoreapp3.0 netcoreapp3.1
.NET Standard netstandard2.1
MonoAndroid monoandroid
MonoMac monomac
MonoTouch monotouch
Tizen tizen60
Xamarin.iOS xamarinios
Xamarin.Mac xamarinmac
Xamarin.TVOS xamarintvos
Xamarin.WatchOS xamarinwatchos
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on RESTFulSense:

Package Downloads

RESTFulLinq is a library that allows you to send LINQ statements to your .NET API and execute these queries on the server /database in a fluent API fashion.


A .NET Library for essential code according to The Standard


Package Description

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on RESTFulSense:

Repository Stars
This is an open source schooling system, dedicated to provide a better experience for schools needing a management and communication and tutoring system all in one place. This project is aiming toward directing all the software development funds and hours to families in need, the idea of the project is to allow schools to use the system as long as the software funds in the school are directed towards financially disadvantaged families and students.
Version Downloads Last updated
2.9.0 3,065 9/28/2022
2.8.0 1,569 8/29/2022
2.7.0 2,003 7/26/2022
2.6.0 837 7/13/2022
2.5.0 3,456 6/13/2022
2.4.0 15,447 11/11/2021
2.3.0 1,697 10/22/2021
2.2.0 1,644 10/2/2021
2.1.0 196 10/2/2021
2.0.0 1,282 9/7/2021
1.9.0 8,153 6/2/2021
1.8.0 2,522 5/19/2021
1.7.0 16,321 10/17/2020
1.6.0 5,511 8/11/2020
1.5.0 792 8/5/2020
1.4.0 3,121 6/15/2020
1.3.0 318 6/15/2020
1.2.0 830 5/23/2020
1.1.0 419 5/23/2020
1.0.0 2,817 4/30/2020
0.9.0 573 4/25/2020
0.8.0 548 4/19/2020
0.7.0 632 3/17/2020
0.6.0 592 3/16/2020
0.5.0 396 3/15/2020
0.4.0 355 3/15/2020
0.3.0 438 3/13/2020
0.2.0 369 3/12/2020
0.1.0 424 3/12/2020

Introduce simpler exception models for testing