JsonApiDotNetCore

A framework for building JSON:API compliant REST APIs using .NET Core and Entity Framework Core.

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 and pagination. 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.

Getting Started

These are some steps you can take to help you understand what this project is and how you can use it:

• What is JSON:API and why should I use it?
• The JSON:API specification
• Demo Video, Blog
• Our documentation
• Check out the example projects
• Embercasts: Full Stack Ember with ASP.NET Core
• Roadmap

Related Projects

• Performance Reports
• JsonApiDotNetCore.MongoDb
• JsonApiDotNetCore.Marten
• Todo List App

Examples

See the examples directory for up-to-date sample applications. There is also a Todo List App that includes a JADNC API and an EmberJs client.

Installation and Usage

See our documentation for detailed usage.

Models

public class Article : Identifiable
{
    [Attr]
    public string Name { get; set; }
}

Controllers

public class ArticlesController : JsonApiController<Article>
{
    public ArticlesController(IJsonApiOptions options, IResourceService<Article> resourceService,
        ILoggerFactory loggerFactory)
        : base(options, resourceService, loggerFactory)
    {
    }
}

Middleware

public class Startup
{
    public IServiceProvider ConfigureServices(IServiceCollection services)
    {
        services.AddJsonApi<AppDbContext>();
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseRouting();
        app.UseJsonApi();
        app.UseEndpoints(endpoints => endpoints.MapControllers());
    }
}

Development

Restore all NuGet packages with:

dotnet restore

Testing

Running tests locally requires access to a PostgreSQL database. If you have docker installed, this can be propped up via:

docker run --rm --name jsonapi-dotnet-core-testing  -e POSTGRES_DB=JsonApiDotNetCoreExample -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:12.0

And then to run the tests:

dotnet test

Compiler warnings

The Release build configuration is set to fail on warnings. That means when submitting a PR there shouldn't be any compiler warnings because the CI build it set to Release.

Compatibility

A lot of changes were introduced in v4, the following chart should help you with compatibility issues between .NET Core versions.

.NET Core Version	EF Core Version	JADNC Version
2.x	2.x	v3.x
3.x	3.x, 5.x	v4.x
5.x	5.x	v4.x

Trying out the latest build

After each commit, a new prerelease NuGet package is automatically published to AppVeyor at https://ci.appveyor.com/nuget/jsonapidotnetcore. To try it out, follow the next steps:

• In Visual Studio: Tools, NuGet Package Manager, Package Manager Settings, Package Sources
  • Click +
  • Name: AppVeyor JADNC, Source: https://ci.appveyor.com/nuget/jsonapidotnetcore
  • Click Update, Ok
• Open the NuGet package manager console (Tools, NuGet Package Manager, Package Manager Console)
  • Select AppVeyor JADNC as package source
  • Run command: Install-Package JonApiDotNetCore -pre