How zxd60/jsonapidotnetcore1 works
Project type and purpose
• This is a .NET Core framework/library (JsonApiDotNetCore) for quickly building JSON:API–compliant REST APIs on top of ASP-NET Core and Entity Framework Core.
File-structure analysis
• Top-level directories
– src/JsonApiDotNetCore: the core library code divided into submodules (Configuration, Middleware, Controllers, Queries, Serialization, Resources, Services, Repositories, AtomicOperations).
– src/JsonApiDotNetCore.Annotations: attribute-based resource definitions and code-generation hooks.
– src/Examples: sample applications showing typical usage patterns (EF Core, Dapper, multi-tenant, No-EF, etc.).
– docs: static site content, markdown guidance and example HTTP scripts.
– test: extensive integration and unit tests for every module and extension point.
• Configuration files & build scripts
– Directory.Build.props, package-versions.props, CI workflows, PowerShell scripts for bootstrapping Postgres and building.
Architecture and data-flow overview
1. ASP-NET Core Web Host
2. JsonApi middleware pipeline (UseRouting → UseJsonApi)
3. Controllers (BaseJsonApiController, JsonApiController, JsonApiOperationsController)
4. Resource Graph & Configuration (built at startup by ResourceGraphBuilder, JsonApiOptions)
5. Service layer (JsonApiResourceService implementing IResourceQueryService, IResourceCommandService)
6. Repository layer (EntityFrameworkCoreRepository or custom repository)
7. EF Core DbContext(s) (AppDbContext)
8. Physical database (PostgreSQL, SQL Server, etc.)
9. Serialization/Deserialization adapters (JsonConverters, IRequest/IResponse adapters)
10. Atomic Operations pipeline (IOperationsProcessor → Processors → TransactionFactory)
b. Relationships & interactions
• HTTP request enters Web Host → passes through JsonApiMiddleware → routed to a JsonApiController
• Controller uses injected ResourceGraph to locate the correct ResourceDefinition and Service(s)
• Service orchestrates business logic, applying filters/pagination via QueryLayerComposer, then calls into the Repository
• Repository resolves a DbContext instance via IDbContextResolver, issues EF Core LINQ or raw SQL, and returns domain entities
• Service wraps entities into Identifiable wrappers, tracks changes, and returns to Controller
• Controller invokes the JSON:API writer (JsonApiWriter) to render the response
• In atomic operations: a JSON:API operations payload is parsed by JsonApiReader → routed to OperationsProcessor → individual processors (create, update, delete, set relationship) → persisted in a transaction
• On startup: Program.cs registers services via builder.Services.AddJsonApi<AppDbContext>(), triggering scanning of assemblies and building of the ResourceGraph
c. Architectural patterns & principles
• Layered/Clean/Onion architecture with a clear separation of concerns
• Dependency Injection as the primary extensibility mechanism
• Repository pattern + Unit of Work (EF Core DbContext)
• Pipeline pattern for middleware and atomic-operations processing
• Convention over configuration with attribute-based resource definitions
• Open/Closed principle: most modules are extensibility points (IResourceDefinition, IQueryLayerComposer, IResourceService, etc.)
d. Key technologies & frameworks
• ASP-NET Core (Middleware, Controllers, DI)
• Entity Framework Core (DbContext, LINQ, Migrations)
• C# Attributes & Reflection (Resource annotations, assembly scanning)
• JSON:API v1.0 specification