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
  • Middleware and Services
  • Defining Models
    • Specifying Public Attributes
    • Relationships
  • Defining Controllers
    • Non-Integer Type Keys
  • Routing
    • Namespacing and Versioning URLs
  • Defining Custom Data Access Methods
  • Pagination
  • Filtering
  • Sorting
  • Meta
• Tests

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.

• 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.

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

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.

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();

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; }
}

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; }
}

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; }
}

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)
    { }
}

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)
    { }
}

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

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

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

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.

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;
});

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

Resources can be sorted by an attribute:

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

Resource meta can be defined by implementing IHasMeta on the model class:

public class Person : Identifiable<int>, IHasMeta
{
    // ...

    public Dictionary<string, object> GetMeta(IJsonApiContext context)
    {
        return new Dictionary<string, object> {
            { "copyright", "Copyright 2015 Example Corp." },
            { "authors", new string[] { "Jared Nance" } }
        };
    }
}

I am using DotNetCoreDocs to generate sample requests and documentation.

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