JSON API .Net Core

JsonApiDotnetCore provides a framework for building json:api compliant web servers. Unlike other .Net implementations, this library provides all the required middleware to build a complete server. All you need to focus on is defining the resources. However, the library is also fully extensible so you can customize the implementation to meet your specific needs.

Comprehensive Demo
Installation
Generators
Usage
Tests

Comprehensive Demo

The following is a WIP demo showing how to create a web application using this library, EmberJS and PostgreSQL. If there are specific topics you'd like to see in future videos, comment on the playlist.

Installation

Visual Studio

Install-Package JsonApiDotnetCore

project.json

"JsonApiDotNetCore": "1.1.0"

*.csproj

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="JsonApiDotNetCore" Version="1.1.0" />
</ItemGroup>

Click here for the latest NuGet version.

For pre-releases, add the MyGet package feed (https://www.myget.org/F/research-institute/api/v3/index.json) to your nuget configuration.

Generators

You can install the Yeoman generators to make building applications much easier.

Usage

You need to do 3 things:

Add Middleware and Services
Define Models
Define Controllers

I recommend reading the details below, but once you're familiar with the setup, you can use the Yeoman generator to generate the required classes.

Middleware and Services

Add the following to your Startup.ConfigureServices method. Replace AppDbContext with your DbContext.

services.AddJsonApi<AppDbContext>();

Add the middleware to the Startup.Configure method. Note that under the hood, this will call app.UseMvc() so there is no need to add that as well.

app.UseJsonApi();

Defining Models

Your models should inherit Identifiable<TId> where TId is the type of the primary key, like so:

public class Person : Identifiable<Guid>
{ }

You can use the non-generic Identifiable if your primary key is an integer:

public class Person : Identifiable
{ }

If you need to hang annotations or attributes on the Id property, you can override the virtual member:

public class Person : Identifiable
{ 
    [Key]
    [Column("person_id")]
    public override int Id { get; set; }
}

Specifying Public Attributes

If you want an attribute on your model to be publicly available, add the AttrAttribute and provide the outbound name.

public class Person : Identifiable<int>
{
    [Attr("first-name")]
    public string FirstName { get; set; }
}

Relationships

In order for navigation properties to be identified in the model, they should be labeled with the appropriate attribute (either HasOne or HasMany).

public class Person : Identifiable<int>
{
    [Attr("first-name")]
    public string FirstName { get; set; }

    [HasMany("todo-items")]
    public virtual List<TodoItem> TodoItems { get; set; }
}

Dependent relationships should contain a property in the form {RelationshipName}Id. For example, a TodoItem may have an Owner and so the Id attribute should be OwnerId like so:

public class TodoItem : Identifiable<int>
{
    [Attr("description")]
    public string Description { get; set; }

    public int OwnerId { get; set; }

    [HasOne("owner")]
    public virtual Person Owner { get; set; }
}

Defining Controllers

You need to create controllers that inherit from JsonApiController<TEntity> or JsonApiController<TEntity, TId> where TEntity is the model that inherits from Identifiable<TId>.

[Route("api/[controller]")]
public class ThingsController : JsonApiController<Thing>
{
    public ThingsController(
        IJsonApiContext jsonApiContext,
        IEntityRepository<Thing> entityRepository,
        ILoggerFactory loggerFactory) 
    : base(jsonApiContext, entityRepository, loggerFactory)
    { }
}

Non-Integer Type Keys

If your model is using a type other than int for the primary key, you should explicitly declare it in the controller and repository generic type definitions:

[Route("api/[controller]")]
public class ThingsController : JsonApiController<Thing, Guid>
{
    public ThingsController(
        IJsonApiContext jsonApiContext,
        IEntityRepository<Thing, Guid> entityRepository,
        ILoggerFactory loggerFactory) 
    : base(jsonApiContext, entityRepository, loggerFactory)
    { }
}

Routing

By default the library will configure routes for each controller. Based on the recommendations outlined in the JSONAPI spec, routes are hyphenated. For example:

/todo-items --> TodoItemsController
NOT /todoItems

Namespacing and Versioning URLs

You can add a namespace to the URL by specifying it in ConfigureServices:

services.AddJsonApi<AppDbContext>(
    opt => opt.Namespace = "api/v1");

Defining Custom Data Access Methods

You can implement custom methods for accessing the data by creating an implementation of IEntityRepository<TEntity, TId>. If you only need minor changes you can override the methods defined in DefaultEntityRepository<TEntity, TId>. The repository should then be add to the service collection in Startup.ConfigureServices like so:

services.AddScoped<IEntityRepository<MyEntity,Guid>, MyAuthorizedEntityRepository>();

A sample implementation might look like:

public class MyAuthorizedEntityRepository : DefaultEntityRepository<MyEntity>
{
    private readonly ILogger _logger;
    private readonly AppDbContext _context;
    private readonly IAuthenticationService _authenticationService;

    public MyAuthorizedEntityRepository(AppDbContext context,
        ILoggerFactory loggerFactory,
        IJsonApiContext jsonApiContext,
        IAuthenticationService authenticationService)
    : base(context, loggerFactory, jsonApiContext)
    { 
        _context = context;
        _logger = loggerFactory.CreateLogger<MyEntityRepository>();
        _authenticationService = authenticationService;
    }

    public override IQueryable<MyEntity> Get()
    {
        return base.Get().Where(e => e.UserId == _authenticationService.UserId);
    }
}

For more examples, take a look at the customization tests in ./test/JsonApiDotNetCoreExampleTests/Acceptance/Extensibility.

Pagination

Resources can be paginated. The following query would set the page size to 10 and get page 2.

?page[size]=10&page[number]=2

If you would like pagination implemented by default, you can specify the page size when setting up the services:

 services.AddJsonApi<AppDbContext>(
     opt => opt.DefaultPageSize = 10);

Total Record Count

The total number of records can be added to the document meta by setting it in the options:

services.AddJsonApi<AppDbContext>(opt =>
{
    opt.DefaultPageSize = 5;
    opt.IncludeTotalRecordCount = true;
});

Filtering

You can filter resources by attributes using the filter query parameter. By default, all attributes are filterable. The filtering strategy we have selected, uses the following form:

?filter[attribute]=value

For operations other than equality, the query can be prefixed with an operation identifier):

?filter[attribute]=eq:value
?filter[attribute]=lt:value
?filter[attribute]=gt:value
?filter[attribute]=le:value
?filter[attribute]=ge:value
?filter[attribute]=like:value

Sorting

Resources can be sorted by an attribute:

?sort=attribute // ascending
?sort=-attribute // descending

Tests

I am using DotNetCoreDocs to generate sample requests and documentation.

To run the tests, start a postgres server and verify the connection properties define in /test/JsonApiDotNetCoreExampleTests/appsettings.json
cd ./test/JsonApiDotNetCoreExampleTests
dotnet test
cd ./src/JsonApiDotNetCoreExample
dotnet run
open http://localhost:5000/docs

jfhs/json-api-dotnet-core