RESTFulSense 2.5.0
See the version list below for details.
dotnet add package RESTFulSense --version 2.5.0
NuGet\Install-Package RESTFulSense -Version 2.5.0
<PackageReference Include="RESTFulSense" Version="2.5.0" />
paket add RESTFulSense --version 2.5.0
#r "nuget: RESTFulSense, 2.5.0"
// Install RESTFulSense as a Cake Addin #addin nuget:?package=RESTFulSense&version=2.5.0 // Install RESTFulSense as a Cake Tool #tool nuget:?package=RESTFulSense&version=2.5.0
<p align="center"> <img width="25%" height="25%" src="https://raw.githubusercontent.com/hassanhabib/RESTFulSense/master/RESTFulSense/Resources/api.png"> </p>
RESTFulSense
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:
[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));
<br />
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();
<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}")
.ReturnsAsync(student);
<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: hassanhabib@live.com <br />
Huge thanks to Mr. Brian Parker @BrianLParker for his RESTfulSense Web Assembly effort.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.1 is compatible. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.1
- Microsoft.AspNetCore.Mvc.Core (>= 2.2.5)
- Newtonsoft.Json (>= 13.0.1)
- Xeption (>= 1.7.0)
NuGet packages (10)
Showing the top 5 NuGet packages that depend on RESTFulSense:
Package | Downloads |
---|---|
Standard.AI.OpenAI
A Standardized .NET library for OpenAI Integrations. |
|
TheStandardBox.Data
A .NET Library for essential code according to The Standard |
|
ISL.Providers.ReIdentification.Necs
ISL.Providers.ReIdentification.Necs provides a re-identification implementation the NECS Api. |
|
RESTFulLinq
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. |
|
EventHighway
Standard-Compliant Open-Source Pub/Sub .NET library for managing events in distributed systems. |
GitHub repositories (2)
Showing the top 2 popular GitHub repositories that depend on RESTFulSense:
Repository | Stars |
---|---|
hassanhabib/OtripleS
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.
|
|
hassanhabib/Standard.AI.OpenAI
Standard-Compliant .NET library for Open AI
|
Version | Downloads | Last updated |
---|---|---|
3.1.0 | 17,483 | 9/19/2024 |
3.0.0 | 20,610 | 5/20/2024 |
2.20.0 | 14,898 | 5/2/2024 |
2.19.0 | 383 | 4/28/2024 |
2.18.0 | 4,121 | 4/1/2024 |
2.17.0 | 18,802 | 1/14/2024 |
2.16.0 | 13,515 | 12/30/2023 |
2.15.0 | 45,977 | 5/5/2023 |
2.14.0 | 202 | 5/4/2023 |
2.13.0 | 59,357 | 3/30/2023 |
2.12.0 | 8,730 | 3/24/2023 |
2.11.0 | 2,312 | 3/19/2023 |
2.10.0 | 1,818 | 3/14/2023 |
2.9.0 | 28,795 | 9/28/2022 |
2.8.0 | 4,508 | 8/29/2022 |
2.7.0 | 2,409 | 7/26/2022 |
2.6.0 | 1,516 | 7/13/2022 |
2.5.0 | 3,931 | 6/13/2022 |
2.4.0 | 21,763 | 11/11/2021 |
2.3.0 | 1,874 | 10/22/2021 |
2.2.0 | 1,844 | 10/2/2021 |
2.1.0 | 351 | 10/2/2021 |
2.0.0 | 1,501 | 9/7/2021 |
1.9.0 | 13,038 | 6/2/2021 |
1.8.0 | 2,768 | 5/19/2021 |
1.7.0 | 21,074 | 10/17/2020 |
1.6.0 | 5,743 | 8/11/2020 |
1.5.0 | 945 | 8/5/2020 |
1.4.0 | 3,599 | 6/15/2020 |
1.3.0 | 477 | 6/15/2020 |
1.2.0 | 964 | 5/23/2020 |
1.1.0 | 556 | 5/23/2020 |
1.0.0 | 2,969 | 4/30/2020 |
0.9.0 | 720 | 4/25/2020 |
0.8.0 | 713 | 4/19/2020 |
0.7.0 | 1,379 | 3/17/2020 |
0.6.0 | 731 | 3/16/2020 |
0.5.0 | 518 | 3/15/2020 |
0.4.0 | 504 | 3/15/2020 |
0.3.0 | 553 | 3/13/2020 |
0.2.0 | 514 | 3/12/2020 |
0.1.0 | 1,117 | 3/12/2020 |
Support media types for POST & PUT