Repository files navigation

Plug-n-play implementation ofIResourceRepository<TResource, TId>, allowing you to useMongoDB with yourJsonApiDotNetCore API projects.

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

1. Install the JsonApiDotNetCore.MongoDb package:

   dotnet add package JsonApiDotNetCore.MongoDb

2. Declare your entities, annotated with JsonApiDotNetCore attributes:

   #nullable enable[Resource]publicclassPerson:HexStringMongoIdentifiable{[Attr]publicstring?FirstName{get;set;}[Attr]publicstringLastName{get;set;}=null!;}

3. Configure MongoDB and JsonApiDotNetCore inProgram.cs, seeding the database with sample data:

   varbuilder=WebApplication.CreateBuilder(args);builder.Services.AddSingleton(_=>newMongoClient("mongodb://localhost:27017").GetDatabase("ExampleDbName"));builder.Services.AddJsonApi(options=>{options.UseRelativeLinks=true;options.IncludeTotalResourceCount=true;},resources: resourceGraphBuilder=>resourceGraphBuilder.Add<Person,string?>());builder.Services.AddJsonApiMongoDb();builder.Services.AddResourceRepository<MongoRepository<Person,string?>>();varapp=builder.Build();app.UseRouting();app.UseJsonApi();app.MapControllers();vardatabase=app.Services.GetRequiredService<IMongoDatabase>();awaitCreateSampleDataAsync(database);app.Run();staticasyncTaskCreateSampleDataAsync(IMongoDatabasedatabase){awaitdatabase.DropCollectionAsync(nameof(Person));awaitdatabase.GetCollection<Person>(nameof(Person)).InsertManyAsync(new[]{newPerson{FirstName="John",LastName="Doe",},newPerson{FirstName="Jane",LastName="Doe",},newPerson{FirstName="John",LastName="Smith",}});}

4. Start your API

   dotnet run

5. Send a GET request to retrieve data:

   GET http://localhost:5000/people?filter=equals(lastName,'Doe')&fields[people]=firstName HTTP/1.1

   Expand to view the JSON response

   {"links": {"self":"/people?filter=equals(lastName,%27Doe%27)&fields[people]=firstName","first":"/people?filter=equals(lastName,%27Doe%27)&fields%5Bpeople%5D=firstName","last":"/people?filter=equals(lastName,%27Doe%27)&fields%5Bpeople%5D=firstName"  },"data": [    {"type":"people","id":"680cae2e1759666c5c1e988c","attributes": {"firstName":"John"      },"links": {"self":"/people/680cae2e1759666c5c1e988c"      }    },    {"type":"people","id":"680cae2e1759666c5c1e988d","attributes": {"firstName":"Jane"      },"links": {"self":"/people/680cae2e1759666c5c1e988d"      }    }  ],"meta": {"total":2  }}

builder.Services.AddJsonApi(facade=>facade.AddCurrentAssembly());builder.Services.AddJsonApiMongoDb();builder.Services.AddScoped(typeof(IResourceReadRepository<,>),typeof(MongoRepository<,>));builder.Services.AddScoped(typeof(IResourceWriteRepository<,>),typeof(MongoRepository<,>));builder.Services.AddScoped(typeof(IResourceRepository<,>),typeof(MongoRepository<,>));

Resources that inherit fromHexStringMongoIdentifiable use auto-generated (high-performance) 12-byte hexadecimalObject IDs.You can assign an ID explicitly, but it must match the 12-byte hexadecimal pattern.

To use free-format string IDs, make your resources inherit fromFreeStringMongoIdentifiable instead.When creating a resource without assigning an ID, a 12-byte hexadecimal ID will be auto-generated.

Setoptions.ClientIdGeneration toAllowed orRequired fromProgram.cs to enable API clients to assign IDs. This can be combinedwith both base classes, butFreeStringMongoIdentifiable probably makes the most sense.

• JSON:API relationships arecurrently not supported. Youcan use complex object graphs though, which are stored in a single document.

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

You can run tests without MongoDB on your machine. The following command runs all tests:

dotnettest

A running instance of MongoDB is required to run the examples.If you have docker installed, you can launch MongoDB in a container with the following command:

pwsh run-docker-mongodb.ps1

And then to run the API:

dotnet run --project src/Examples/GettingStarted

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

pwsh Build.ps1