A framework for building JSON:API compliant REST APIs using ASP.NET Core and Entity Framework Core. Includes support for the Atomic Operations extension.
The ultimate goal of this library is to eliminate as much boilerplate as possible by offering out-of-the-box features, such as sorting, filtering, pagination, sparse fieldset selection, and side-loading related resources. You just need to focus on defining the resources and implementing your custom business logic. This library has been designed around dependency injection, making extensibility incredibly easy.
Note
OpenAPI support is now available, currently in preview. Give it a try!
The following steps describe how to create a JSON:API project.
Create a new ASP.NET Core Web API project:
dotnet new webapi --no-openapi --use-controllers --name ExampleJsonApi cd ExampleJsonApi
Install the JsonApiDotNetCore package, along with your preferred Entity Framework Core provider:
dotnet add package JsonApiDotNetCore dotnet add package Microsoft.EntityFrameworkCore.Sqlite
Declare your entities, annotated with JsonApiDotNetCore attributes:
[Resource]
public class Person : Identifiable<long>
{
[Attr] public string? FirstName { get; set; }
[Attr] public string LastName { get; set; } = null!;
[HasMany] public ISet<Person> Children { get; set; } = new HashSet<Person>();
}Define your DbContext, seeding the database with sample data:
public class AppDbContext(DbContextOptions<AppDbContext> options) : DbContext(options)
{
public DbSet<Person> People => Set<Person>();
protected override void OnConfiguring(DbContextOptionsBuilder builder)
{
builder.UseSqlite("Data Source=SampleDb.db");
builder.UseAsyncSeeding(async (dbContext, _, cancellationToken) =>
{
dbContext.Set<Person>().Add(new Person
{
FirstName = "John",
LastName = "Doe",
Children =
{
new Person
{
FirstName = "Baby",
LastName = "Doe"
}
}
});
await dbContext.SaveChangesAsync(cancellationToken);
});
}
}Configure Entity Framework Core and JsonApiDotNetCore in Program.cs:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<AppDbContext>();
builder.Services.AddJsonApi<AppDbContext>(options =>
{
options.UseRelativeLinks = true;
options.IncludeTotalResourceCount = true;
});
var app = builder.Build();
app.UseRouting();
app.UseJsonApi();
app.MapControllers();
await CreateDatabaseAsync(app.Services);
app.Run();
static async Task CreateDatabaseAsync(IServiceProvider serviceProvider)
{
await using var scope = serviceProvider.CreateAsyncScope();
var dbContext = scope.ServiceProvider.GetRequiredService<AppDbContext>();
await dbContext.Database.EnsureDeletedAsync();
await dbContext.Database.EnsureCreatedAsync();
}Start your API
Send a GET request to retrieve data:
GET http://localhost:5000/people?filter=equals(firstName,'John')&include=children HTTP/1.1Expand to view the JSON response
{
"links": {
"self": "/people?filter=equals(firstName,%27John%27)&include=children",
"first": "/people?filter=equals(firstName,%27John%27)&include=children",
"last": "/people?filter=equals(firstName,%27John%27)&include=children"
},
"data": [
{
"type": "people",
"id": "1",
"attributes": {
"firstName": "John",
"lastName": "Doe"
},
"relationships": {
"children": {
"links": {
"self": "/people/1/relationships/children",
"related": "/people/1/children"
},
"data": [
{
"type": "people",
"id": "2"
}
]
}
},
"links": {
"self": "/people/1"
}
}
],
"included": [
{
"type": "people",
"id": "2",
"attributes": {
"firstName": "Baby",
"lastName": "Doe"
},
"relationships": {
"children": {
"links": {
"self": "/people/2/relationships/children",
"related": "/people/2/children"
}
}
},
"links": {
"self": "/people/2"
}
}
],
"meta": {
"total": 1
}
}The following links explain what this project provides, why it exists, and how you can use it.
The following chart should help you pick the best version, based on your environment. See also our versioning policy.
JsonApiDotNetCore Status .NET Entity Framework Core master Preview 9 9 8 8, 9 5.7.0+ Stable 9 9 8 8, 9 5.5.0-5.6.0 Stable 9 9 8 8, 9 7 7 6 6, 7 5.0.3-5.4.0 Stable 7 7 6 6, 7 5.0.0-5.0.2 Stable 6 6 4.x Stable 6 5 5 5 Core 3.1 3.1, 5 3.x Stable Core 2.x 2.x Trying out the latest buildAfter each commit to the master branch, a new pre-release NuGet package is automatically published to feedz.io. To try it out, follow the steps below:
Create a nuget.config file in the same directory as your .sln file, with the following contents:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<add key="json-api-dotnet" value="https://f.feedz.io/json-api-dotnet/jsonapidotnetcore/nuget/index.json" />
<add key="NuGet" value="https://api.nuget.org/v3/index.json" />
</packageSources>
</configuration>In your IDE, browse the list of packages from the json-api-dotnet feed. Make sure pre-release packages are included in the list.
Have a question, found a bug or want to submit code changes? See our contributing guidelines.
To build the code from this repository locally, run:
Running tests locally requires access to a PostgreSQL database. If you have docker installed, this can be started via:
pwsh run-docker-postgres.ps1
And then to run the tests:
Alternatively, to build, run all tests, generate code coverage and NuGet packages:
We are grateful to the following sponsors, who provide the team with a no-cost license for using their tools.
Do you like this project? Consider to sponsor, or just reward us by giving our repository a star.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4