Aiursoft.AiurProtocol.Abstractions
8.0.0
dotnet add package Aiursoft.AiurProtocol.Abstractions --version 8.0.0
NuGet\Install-Package Aiursoft.AiurProtocol.Abstractions -Version 8.0.0
<PackageReference Include="Aiursoft.AiurProtocol.Abstractions" Version="8.0.0" />
paket add Aiursoft.AiurProtocol.Abstractions --version 8.0.0
#r "nuget: Aiursoft.AiurProtocol.Abstractions, 8.0.0"
// Install Aiursoft.AiurProtocol.Abstractions as a Cake Addin #addin nuget:?package=Aiursoft.AiurProtocol.Abstractions&version=8.0.0 // Install Aiursoft.AiurProtocol.Abstractions as a Cake Tool #tool nuget:?package=Aiursoft.AiurProtocol.Abstractions&version=8.0.0
AiurProtocol
AiurProtocol defines an API programming practice to easily build a RESTful API. It simplifies the process of
- Auto HTTP request path building
- Strong-typed API model sharing
- Auto HTTP status code translation
- Auto error handling\error pass through
- Auto input model validation\local validation
- Auto serialization and deserialization
- Document generation
And the API it built is also standard Restful HTTP API, so you can call it with any programming language.
With AiurProtocol, you can focus on designing your API and forget about those complications!
Why this project?
API development is a challenging task that requires handling various aspects such as HTTP status codes, error handling, input validation, documentation writing, and log checking. However, this project aims to simplify the API development process by providing a unified best practice approach. By following this approach, developers can efficiently handle HTTP status codes, error handling, input validation, documentation writing, and log checking. This project's goal is to save time and effort, allowing developers to focus more on developing new features.
Installation
Run the following command to install Aiursoft.AiurProtocol.Server
to your ASP.NET Core project from nuget.org:
dotnet add package Aiursoft.AiurProtocol.Server
Run the following command to install Aiursoft.AiurProtocol
to your SDK project which sending requests to your server from nuget.org:
dotnet add package Aiursoft.AiurProtocol
How to use on Server
Register AiurProtocol in your Startup.cs
// Your startup.cs on server
using Aiursoft.AiurProtocol.Server;
public void ConfigureServices(IServiceCollection services)
{
services
.AddControllers()
.AddAiurProtocol(); // <---- Add this after add controllers!
}
Now you can go to your Controller and return the protocol!
// Your controller
using Aiursoft.AiurProtocol.Server;
[ApiExceptionHandler(
PassthroughRemoteErrors = true,
PassthroughAiurServerException = true)]
[ApiModelStateChecker]
public class HomeController : ControllerBase
{
[Route("/api/hello-world")]
public IActionResult Index()
{
return this.Protocol(Code.ResultShown, "Welcome to this API project!");
}
}
How to use it to build an SDK
Now you need to write an SDK for your API.
After creating a new class library project, add the dependencies:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net7.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Aiursoft.AiurProtocol" Version="6.0.7" />
</ItemGroup>
</Project>
Write the following method:
// In SDK
using Aiursoft.AiurProtocol;
using Microsoft.Extensions.DependencyInjection;
public class DemoServerConfig
{
public string Instance { get; set; } = string.Empty;
}
public class DemoAccess
{
private readonly AiurProtocolClient _http;
private readonly DemoServerConfig _demoServerLocator;
public DemoAccess(
AiurProtocolClient http,
IOptions<DemoServerConfig> demoServerLocator)
{
_http = http;
_demoServerLocator = demoServerLocator.Value;
}
public async Task<AiurResponse> IndexAsync()
{
var url = new AiurApiEndpoint(host: _demoServerLocator.Instance, route: "/api/hello-world", param: new {});
var result = await _http.Get<AiurResponse>(url);
return result;
}
}
public static IServiceCollection AddDemoService(this IServiceCollection services, string endPointUrl)
{
services.AddAiurProtocolClient();
services.Configure<DemoServerConfig>(options => options.Instance = endPointUrl);
services.AddScoped<DemoAccess>();
return services;
}
How to use your new SDK
Now you can write a new console app to use your new SDK to call your server!
// To get your SDK:
var services = new ServiceCollection();
services.AddDemoService(endpointUrl);
var serviceProvider = services.BuildServiceProvider();
var sdk = serviceProvider.GetRequiredService<DemoAccess>(); // Or from dependency injection
// To use your SDK:
var result = await sdk?.IndexAsync()!;
That's it! It will use your SDK to generate a new call to your server, and the result is right at your hand!
Advanced usage
- General
- API Design samples
- Server Programming features
- SDK Programming
Future features
It will support the following features in the future:
- API rate limit
- API version control
- API documentation
- API request logging and report
How to contribute
There are many ways to contribute to the project: logging bugs, submitting pull requests, reporting issues, and creating suggestions.
Even if you with push rights on the repository, you should create a personal fork and create feature branches there when you need them. This keeps the main repository clean and your workflow cruft out of sight.
We're also interested in your feedback on the future of this project. You can submit a suggestion or feature request through the issue tracker. To make this process more effective, we're asking that these include more information to help define them more clearly.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. 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. |
-
net8.0
- Newtonsoft.Json (>= 13.0.3)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on Aiursoft.AiurProtocol.Abstractions:
Package | Downloads |
---|---|
Aiursoft.AiurProtocol
API Communication practice |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
8.0.0 | 1,213 | 2/19/2024 |
7.0.10 | 370 | 1/30/2024 |
7.0.9 | 191 | 1/18/2024 |
7.0.8 | 2,196 | 11/12/2023 |
7.0.7 | 317 | 11/2/2023 |
7.0.6 | 299 | 11/2/2023 |
7.0.5 | 381 | 10/31/2023 |
7.0.2 | 694 | 9/23/2023 |
7.0.1 | 354 | 9/13/2023 |
7.0.0 | 552 | 9/5/2023 |
6.0.11 | 269 | 8/20/2023 |
6.0.10 | 524 | 7/9/2023 |
6.0.9 | 414 | 7/9/2023 |
6.0.8 | 395 | 7/3/2023 |
6.0.7 | 409 | 6/26/2023 |
6.0.6 | 256 | 6/25/2023 |
6.0.5 | 267 | 6/24/2023 |
6.0.4 | 245 | 6/23/2023 |
6.0.3 | 208 | 6/23/2023 |
6.0.2 | 231 | 6/23/2023 |
6.0.1 | 228 | 6/23/2023 |
6.0.0 | 229 | 6/19/2023 |
1.0.0 | 255 | 6/19/2023 |