Repository files navigation

A framework for buildingJSON:API compliant REST APIs using ASP.NET Core and Entity Framework Core. Includes support for theAtomic 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.

The following steps describe how to create a JSON:API project.

1. Create a new ASP.NET Core Web API project:

   dotnet new webapi --no-openapi --use-controllers --name ExampleJsonApicd ExampleJsonApi

2. Install the JsonApiDotNetCore package, along with your preferred Entity Framework Core provider:

   dotnet add package JsonApiDotNetCoredotnet add package Microsoft.EntityFrameworkCore.Sqlite

3. Declare your entities, annotated with JsonApiDotNetCore attributes:

   [Resource]publicclassPerson:Identifiable<long>{[Attr]publicstring?FirstName{get;set;}[Attr]publicstringLastName{get;set;}=null!;[HasMany]publicISet<Person>Children{get;set;}=newHashSet<Person>();}

4. Define yourDbContext, seeding the database with sample data:

   publicclassAppDbContext(DbContextOptions<AppDbContext>options):DbContext(options){publicDbSet<Person>People=>Set<Person>();protectedoverridevoidOnConfiguring(DbContextOptionsBuilderbuilder){builder.UseSqlite("Data Source=SampleDb.db");builder.UseAsyncSeeding(async(dbContext,_,cancellationToken)=>{dbContext.Set<Person>().Add(newPerson{FirstName="John",LastName="Doe",Children={newPerson{FirstName="Baby",LastName="Doe"}}});awaitdbContext.SaveChangesAsync(cancellationToken);});}}

5. Configure Entity Framework Core and JsonApiDotNetCore inProgram.cs:

   varbuilder=WebApplication.CreateBuilder(args);builder.Services.AddDbContext<AppDbContext>();builder.Services.AddJsonApi<AppDbContext>(options=>{options.UseRelativeLinks=true;options.IncludeTotalResourceCount=true;});varapp=builder.Build();app.UseRouting();app.UseJsonApi();app.MapControllers();awaitCreateDatabaseAsync(app.Services);app.Run();staticasyncTaskCreateDatabaseAsync(IServiceProviderserviceProvider){awaitusingvarscope=serviceProvider.CreateAsyncScope();vardbContext=scope.ServiceProvider.GetRequiredService<AppDbContext>();awaitdbContext.Database.EnsureDeletedAsync();awaitdbContext.Database.EnsureCreatedAsync();}

6. Start your API

   dotnet run

7. Send a GET request to retrieve data:

   GET http://localhost:5000/people?filter=equals(firstName,'John')&include=children HTTP/1.1

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

• What is JSON:API and why should I use it? (blog, 2017)
• Pragmatic JSON:API Design (video, 2017)
• JSON:API and JsonApiDotNetCore (video, 2021)
• JsonApiDotNetCore Release 4.0 (blog, 2020)
• JSON:API, ASP.NET Core, EmberJS (video, 2017)
• Embercasts: Full Stack Ember with ASP.NET Core (paid course, 2017)

• JsonApiDotNetCore documentation
• The JSON:API specification
• JsonApiDotNetCore roadmap

• Theexamples directory provides ready-to-run sample API projects, which are documentedhere.
• Theintegration tests directory covers many advanced use cases, which are documentedhere.This includes topics such as batching, multi-tenancy, authorization, soft-deletion, obfuscated IDs, resource inheritance, alternate routing, custom metadata, error handling and logging.
• TheEmber.js Todo List App showcases a JsonApiDotNetCore API and an Ember.js client with token authentication.

• JsonApiDotNetCore.MongoDb
• Ember.js Todo List App
• Performance Reports

The following chart should help you pick the best version, based on your environment.See also ourversioning policy.

After each commit to the master branch, a new pre-release NuGet package is automatically published tofeedz.io.To try it out, follow the steps below:

1. Create anuget.config file in the same directory as your .sln file, with the following contents:

   <?xml version="1.0" encoding="utf-8"?><configuration>  <packageSources>    <addkey="json-api-dotnet"value="https://f.feedz.io/json-api-dotnet/jsonapidotnetcore/nuget/index.json" />    <addkey="NuGet"value="https://api.nuget.org/v3/index.json" />  </packageSources></configuration>

2. In your IDE, browse the list of packages from thejson-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 ourcontributing guidelines.

To build the code from this repository locally, run:

dotnet build

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:

dotnettest

Alternatively, to build, run all tests, generate code coverage and NuGet packages:

pwsh Build.ps1

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 tosponsor, or just reward us by giving our repository a star.