dFakto.Rest.Abstractions
1.0.0
dotnet add package dFakto.Rest.Abstractions --version 1.0.0
NuGet\Install-Package dFakto.Rest.Abstractions -Version 1.0.0
<PackageReference Include="dFakto.Rest.Abstractions" Version="1.0.0" />
paket add dFakto.Rest.Abstractions --version 1.0.0
#r "nuget: dFakto.Rest.Abstractions, 1.0.0"
// Install dFakto.Rest.Abstractions as a Cake Addin #addin nuget:?package=dFakto.Rest.Abstractions&version=1.0.0 // Install dFakto.Rest.Abstractions as a Cake Tool #tool nuget:?package=dFakto.Rest.Abstractions&version=1.0.0
dFakto.Rest
According to Roy Fielding, you may call your API a REST API only if you make use of hypertext
The dFakto.Rest project contains components to ease the creation of REST API following the best practices described in the Hypertext Application Language specification and in books like "Rest In Practice" and "REST API Design Cookbook".
The project is composed of 3 components
- dFakto.Rest.Abstractions project contains base classes and interfaces
- dFakto.Rest.System.text.Json an implementation based on System.Text.Json
- dFakto.Rest.AspNetCore.Mvc contains component to ease integration of dFakto.Rest into ASPNET Core projects.
Quick example to create a Resource :
using dFakto.Rest;
using dFakto.Rest.System.text.Json;
var factory = new ResourceFactory(options);
var author = factory.Create(new Uri("http://example.com/api/authors/12345"))
.Add(new
{
Name = "Marcel Proust",
BirthDate = new DateTime(1871, 7, 10)
});
var result = factory.Create(new Uri("http://example.com/api/books/in-search-of-lost-time"))
.Add(new {Title = "In Search of Lost Time"})
.AddEmbedded("author",author);
var resourceJsonSerializer = _factory.CreateSerializer();
var json = await resourceJsonSerializer.Serialize(result);
Will return the following Json
{
"_links": {
"self": {
"href": "http://example.com/api/book/in-search-of-lost-time"
}
},
"_embedded": {
"author": {
"_links": {
"self": {
"href": "http://example.com/api/users/12345"
}
},
"name" : "Marcel Proust",
"birthdate": "1871-07-10T00:00:00.00"
}
},
"title": "In Search of Lost Time"
}
How to integrate into ASP.NET Core project
First add the reference to your project
Install-Package dFakto.Rest.Asbtractions
Install-Package dFakto.Rest.System.Text.Json
Install-Package dFakto.Rest.AspNetCore.Mvc
Update your Startup.cs file
public void ConfigureServices(IServiceCollection services)
{
...
services.AddRest(new JsonSerializerOptions()
{
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault
});
// Register Formatter to use application/hal+json MediaType
services.AddControllers(x =>
{
x.InputFormatters.Add(new ResourceInputFormatter());
x.OutputFormatters.Add(new ResourceOutputFormatter());
});
...
}
Example of Controller
class MyController : Controller
{
private IResourceFactory _factory;
// Inject Resource Factory
public MyController(IResourceFactory resourceFactory){
_factory = resourceFactory;
}
[HttpGet("/{id}",Name = "getbyid")]
public ActionResult<IResource> Get(int id, [FromQuery] ResourceRequest request)
{
var domainEntity = GetDomainEntity();
var result = _resourceFactory.Create(Url.LinkUri("getbyid", new {id = sampleValue.Id}))
.AddLink("somelink", new Link(Url.LinkUri("getallvalues")))
.Add(sampleValue);
return Ok(result);
}
}
For more information, look at the sample project
Expand Middleware (Hypertext Cache Pattern)
A special middleware can be integrated to load linked resource as embedded automatically based on the "expand" parameter
To enable this middleware, you have to update your Startup.cs file
Register and configure the Middleware in Dependency Injection
public void ConfigureServices(IServiceCollection services)
{
...
services.AddExpandMiddleware(o => o.RequestTimeout = 10);
...
}
Insert the Middleware
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
...
app.UseExpandMiddleware(); // Register Expand Middleware before UseMvc() call.
app.UseEndpoints(endpoints => {
endpoints.MapControllers();
});
...
}
Once the Middleware integrated, you can pass the name of the link you want to retrieve as embedded resource using the expand query string parameter
Example:
GET http://myapi/resource
{
"_links": {
"self": {"href": "http://myapi/resource"},
"other": {"href": "http://myapi/other/2323"}
},
"field1": "1"
}
Adding the "expand" query string parameter and specify the link we want to expand
GET http://myapi/resource?expand=other
{
"_links": {
"self": {"href": "http://myapi/resource"},
"other": {"href": "http://myapi/other/2323"}
},
"_embedded": {
"other": {
"_links": {
"self": {"href": "http://myapi/other/2323"}
},
"field1":4,
"field2":10,
"field3":"hello",
}
},
"field1": "1"
}
The returned resource will contains the embedded without changing anything in the Controller.
It is possible to specify the name of an embedded resource link by using the format "embedded.link" as value for the expand parameter.
As the middleware retrieve the resources using HTTP GET calls, it may be more efficient to let the controller retrieve the resource if it can be retrieve locally (in the same controller or in another Controller). If the controller process the "expand" parameter and add the embedded resource, the middleware will not process it again.
Delimited values parameters
ASP.NET Core MVC does not support delimited values for query string parameters because it is not standard.
For example, the uri http://someuri/api?param=val1,val2,val3 cannot be mapped as a string[] in your request object. (To do so, you have to repeat the attribute name "?param=val1¶m=val2...")
To support the delimited values parameters, you can register the following ProviderFactory
services.AddMvc(options => options.ValueProviderFactories.AddDelimitedValueProviderFactory(','))
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
- No dependencies.
NuGet packages (2)
Showing the top 2 NuGet packages that depend on dFakto.Rest.Abstractions:
Package | Downloads |
---|---|
dFakto.Rest.AspNetCore.Mvc
Package Description |
|
dFakto.Rest.System.Text.Json
Package Description |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
1.0.0 | 3,101 | 8/3/2023 |
1.0.0-rc4 | 522 | 5/2/2023 |
1.0.0-rc3 | 196 | 5/2/2023 |
1.0.0-rc2 | 263 | 4/17/2023 |
1.0.0-rc.7 | 445 | 6/1/2023 |
1.0.0-rc.6 | 890 | 5/16/2023 |
1.0.0-rc.5 | 294 | 5/11/2023 |
1.0.0-beta6 | 2,890 | 10/29/2021 |
1.0.0-beta5 | 266 | 10/21/2021 |
1.0.0-beta4 | 308 | 10/21/2021 |
1.0.0-beta2 | 374 | 10/18/2021 |
1.0.0-beta1 | 291 | 10/15/2021 |