Generic resource definitions (#832)

* Generic resource definitions

Made resource definitions a first-class pluggable extensibility point, similar to resource services and repositories. So developers now can derive from JsonApiResourceDefinition, implement IResourceDefinition, or insert base classes in the type hierarchy to share common logic. Such a base class can then be registered as an open generic, so that all resources will use that (unless the container finds a non-generic class, which is a better match) instead of the built-in JsonApiResourceDefinition.

To accomplish this, I had to split up ResourceDefinition into two:
- JsonApiResourceDefinition is highly pluggable like described above
- ResourceHooksDefinition contains just the hook callbacks

This way, the recursive resolve logic for resource hooks remains as-is. Since it did not use IResourceDefinitionProvider, that type has been replaced with IResourceDefinitionAccessor, which invokes the requested callbacks directly on the found class. What used to be IResourceDefinition (an intermediate type to invoke callbacks on) no longer exists.

* Only scan for hooks when enabled in options
Replaced IHasMeta with IResourceDefinition method

* Fix broken cibuild

* Review feedback

* Made ResourceDefinitionAccessor.GetResourceDefinition protected

* Renamed IRequestMeta to IResponseMeta; updated documentation

* quotes

* Review feedback

Author: Bart Koelman

benchmarks/DependencyFactory.cs

@@ -1,8 +1,5 @@
-using System;
 using JsonApiDotNetCore.Configuration;
-using JsonApiDotNetCore.Resources;
 using Microsoft.Extensions.Logging.Abstractions;
-using Moq;
 
 namespace Benchmarks
 {
@@ -14,15 +11,5 @@ public static IResourceGraph CreateResourceGraph(IJsonApiOptions options)
             builder.Add<BenchmarkResource>(BenchmarkResourcePublicNames.Type);
             return builder.Build();
         }
-
-        public static IResourceDefinitionProvider CreateResourceDefinitionProvider(IResourceGraph resourceGraph)
-        {
-            var resourceDefinition = new ResourceDefinition<BenchmarkResource>(resourceGraph);
-
-            var resourceDefinitionProviderMock = new Mock<IResourceDefinitionProvider>();
-            resourceDefinitionProviderMock.Setup(provider => provider.Get(It.IsAny<Type>())).Returns(resourceDefinition);
-            
-            return resourceDefinitionProviderMock.Object;
-        }
     }
 }

benchmarks/Serialization/JsonApiSerializerBenchmarks.cs

@@ -4,6 +4,7 @@
 using JsonApiDotNetCore.Middleware;
 using JsonApiDotNetCore.Queries;
 using JsonApiDotNetCore.QueryStrings.Internal;
+using JsonApiDotNetCore.Resources;
 using JsonApiDotNetCore.Serialization;
 using JsonApiDotNetCore.Serialization.Building;
 using Moq;
@@ -46,9 +47,9 @@ private static FieldsToSerialize CreateFieldsToSerialize(IResourceGraph resource
                 new SparseFieldSetQueryStringParameterReader(request, resourceGraph)
             };
 
-            var resourceDefinitionProvider = DependencyFactory.CreateResourceDefinitionProvider(resourceGraph);
+            var accessor = new Mock<IResourceDefinitionAccessor>().Object;
 
-            return new FieldsToSerialize(resourceGraph, constraintProviders, resourceDefinitionProvider);
+            return new FieldsToSerialize(resourceGraph, constraintProviders, accessor);
         }
 
         [Benchmark]

docs/usage/meta.md

@@ -1,43 +1,60 @@
 # Metadata
 
-Non-standard metadata can be added to your API responses in two ways: Resource and Request Meta. In the event of a key collision, the Request Meta will take precendence.
+Top-level metadata can be added to your API responses in two ways: globally and per resource type. In the event of a key collision, the resource meta will take precendence.
 
-## Resource Meta
+## Global Meta
 
-Resource Meta is metadata defined on the resource itself by implementing the `IHasMeta` interface.
+Global metadata can be added by registering a service that implements `IResponseMeta`.
+This is useful if you need access to other registered services to build the meta object.
 
 ```c#
-public class Person : Identifiable, IHasMeta
+public class ResponseMetaService : IResponseMeta
 {
+    public ResponseMetaService(/*...other dependencies here */) {
+        // ...
+    }
+
     public Dictionary<string, object> GetMeta()
     {
         return new Dictionary<string, object>
         {
             {"copyright", "Copyright 2018 Example Corp."},
-            {"authors", new[] {"John Doe"}}
+            {"authors", new string[] {"John Doe"}}
         };
     }
 }
 ```
 
-## Request Meta
+```json
+{
+  "meta": {
+    "copyright": "Copyright 2018 Example Corp.",
+    "authors": [
+      "John Doe"
+    ]
+  },
+  "data": {
+    // ...
+  }
+}
+```
 
-Request Meta can be added by injecting a service that implements `IRequestMeta`.
-This is useful if you need access to other injected services to build the meta object.
+## Resource Meta
+
+Resource-specific metadata can be added by implementing `IResourceDefinition<TResource, TId>.GetMeta` (or overriding it on `JsonApiResourceDefinition`):
 
 ```c#
-public class RequestMetaService : IRequestMeta
+public class PersonDefinition : JsonApiResourceDefinition<Person>
 {
-    public RequestMetaService(/*...other dependencies here */) {
-        // ...
+    public PersonDefinition(IResourceGraph resourceGraph) : base(resourceGraph)
+    {
     }
 
-    public Dictionary<string, object> GetMeta()
+    public override IReadOnlyDictionary<string, object> GetMeta()
     {
         return new Dictionary<string, object>
         {
-            {"copyright", "Copyright 2018 Example Corp."},
-            {"authors", new string[] {"John Doe"}}
+            ["notice"] = "Check our intranet at http://www.example.com for personal details."
         };
     }
 }
@@ -46,10 +63,7 @@ public class RequestMetaService : IRequestMeta
 ```json
 {
   "meta": {
-    "copyright": "Copyright 2018 Example Corp.",
-    "authors": [
-      "John Doe"
-    ]
+    "notice": "Check our intranet at http://www.example.com for personal details."
   },
   "data": {
     // ...

src/Examples/JsonApiDotNetCoreExample/Definitions/ArticleDefinition.cs renamed to src/Examples/JsonApiDotNetCoreExample/Definitions/ArticleHooksDefinition.cs

@@ -10,9 +10,9 @@
 
 namespace JsonApiDotNetCoreExample.Definitions
 {
-    public class ArticleDefinition : ResourceDefinition<Article>
+    public class ArticleHooksDefinition : ResourceHooksDefinition<Article>
     {
-        public ArticleDefinition(IResourceGraph resourceGraph) : base(resourceGraph) { }
+        public ArticleHooksDefinition(IResourceGraph resourceGraph) : base(resourceGraph) { }
 
         public override IEnumerable<Article> OnReturn(HashSet<Article> resources, ResourcePipeline pipeline)
         {

src/Examples/JsonApiDotNetCoreExample/Definitions/LockableDefinition.cs renamed to src/Examples/JsonApiDotNetCoreExample/Definitions/LockableHooksDefinition.cs

@@ -9,9 +9,9 @@
 
 namespace JsonApiDotNetCoreExample.Definitions
 {
-    public abstract class LockableDefinition<T> : ResourceDefinition<T> where T : class, IIsLockable, IIdentifiable
+    public abstract class LockableHooksDefinition<T> : ResourceHooksDefinition<T> where T : class, IIsLockable, IIdentifiable
     {
-        protected LockableDefinition(IResourceGraph resourceGraph) : base(resourceGraph) { }
+        protected LockableHooksDefinition(IResourceGraph resourceGraph) : base(resourceGraph) { }
 
         protected void DisallowLocked(IEnumerable<T> resources)
         {

src/Examples/JsonApiDotNetCoreExample/Definitions/PassportDefinition.cs renamed to src/Examples/JsonApiDotNetCoreExample/Definitions/PassportHooksDefinition.cs

@@ -10,9 +10,9 @@
 
 namespace JsonApiDotNetCoreExample.Definitions
 {
-    public class PassportDefinition : ResourceDefinition<Passport>
+    public class PassportHooksDefinition : ResourceHooksDefinition<Passport>
     {
-        public PassportDefinition(IResourceGraph resourceGraph) : base(resourceGraph)
+        public PassportHooksDefinition(IResourceGraph resourceGraph) : base(resourceGraph)
         {
         }
 

src/Examples/JsonApiDotNetCoreExample/Definitions/PersonDefinition.cs

@@ -1,32 +1,29 @@
 using System.Collections.Generic;
-using System.Linq;
 using JsonApiDotNetCore.Configuration;
-using JsonApiDotNetCore.Hooks.Internal.Execution;
 using JsonApiDotNetCore.Resources;
 using JsonApiDotNetCoreExample.Models;
 
 namespace JsonApiDotNetCoreExample.Definitions
 {
-    public class PersonDefinition : LockableDefinition<Person>, IHasMeta
+    public class PersonDefinition : JsonApiResourceDefinition<Person>
     {
-        public PersonDefinition(IResourceGraph resourceGraph) : base(resourceGraph) { }
-
-        public override IEnumerable<string> BeforeUpdateRelationship(HashSet<string> ids, IRelationshipsDictionary<Person> resourcesByRelationship, ResourcePipeline pipeline)
-        {
-            BeforeImplicitUpdateRelationship(resourcesByRelationship, pipeline);
-            return ids;
-        }
-
-        public override void BeforeImplicitUpdateRelationship(IRelationshipsDictionary<Person> resourcesByRelationship, ResourcePipeline pipeline)
+        public PersonDefinition(IResourceGraph resourceGraph) : base(resourceGraph)
         {
-            resourcesByRelationship.GetByRelationship<Passport>().ToList().ForEach(kvp => DisallowLocked(kvp.Value));
         }
 
-        public IReadOnlyDictionary<string, object> GetMeta()
+        public override IReadOnlyDictionary<string, object> GetMeta()
         {
-            return new Dictionary<string, object> {
-                { "copyright", "Copyright 2015 Example Corp." },
-                { "authors", new[] { "Jared Nance", "Maurits Moeys", "Harro van der Kroft" } }
+            return new Dictionary<string, object>
+            {
+                ["license"] = "MIT",
+                ["projectUrl"] = "https://github.com/json-api-dotnet/JsonApiDotNetCore/",
+                ["versions"] = new[]
+                {
+                    "v4.0.0",
+                    "v3.1.0",
+                    "v2.5.2",
+                    "v1.3.1"
+                }
             };
         }
     }

src/Examples/JsonApiDotNetCoreExample/Definitions/PersonHooksDefinition.cs

@@ -0,0 +1,24 @@
+using System.Collections.Generic;
+using System.Linq;
+using JsonApiDotNetCore.Configuration;
+using JsonApiDotNetCore.Hooks.Internal.Execution;
+using JsonApiDotNetCoreExample.Models;
+
+namespace JsonApiDotNetCoreExample.Definitions
+{
+    public class PersonHooksDefinition : LockableHooksDefinition<Person>
+    {
+        public PersonHooksDefinition(IResourceGraph resourceGraph) : base(resourceGraph) { }
+
+        public override IEnumerable<string> BeforeUpdateRelationship(HashSet<string> ids, IRelationshipsDictionary<Person> resourcesByRelationship, ResourcePipeline pipeline)
+        {
+            BeforeImplicitUpdateRelationship(resourcesByRelationship, pipeline);
+            return ids;
+        }
+
+        public override void BeforeImplicitUpdateRelationship(IRelationshipsDictionary<Person> resourcesByRelationship, ResourcePipeline pipeline)
+        {
+            resourcesByRelationship.GetByRelationship<Passport>().ToList().ForEach(kvp => DisallowLocked(kvp.Value));
+        }
+    }
+}

src/Examples/JsonApiDotNetCoreExample/Definitions/TagDefinition.cs renamed to src/Examples/JsonApiDotNetCoreExample/Definitions/TagHooksDefinition.cs

@@ -7,9 +7,9 @@
 
 namespace JsonApiDotNetCoreExample.Definitions
 {
-    public class TagDefinition : ResourceDefinition<Tag>
+    public class TagHooksDefinition : ResourceHooksDefinition<Tag>
     {
-        public TagDefinition(IResourceGraph resourceGraph) : base(resourceGraph) { }
+        public TagHooksDefinition(IResourceGraph resourceGraph) : base(resourceGraph) { }
 
         public override IEnumerable<Tag> BeforeCreate(IResourceHashSet<Tag> affected, ResourcePipeline pipeline)
         {

src/Examples/JsonApiDotNetCoreExample/Definitions/TodoDefinition.cs renamed to src/Examples/JsonApiDotNetCoreExample/Definitions/TodoHooksDefinition.cs

@@ -9,9 +9,9 @@
 
 namespace JsonApiDotNetCoreExample.Definitions
 {
-    public class TodoDefinition : LockableDefinition<TodoItem>
+    public class TodoHooksDefinition : LockableHooksDefinition<TodoItem>
     {
-        public TodoDefinition(IResourceGraph resourceGraph) : base(resourceGraph) { }
+        public TodoHooksDefinition(IResourceGraph resourceGraph) : base(resourceGraph) { }
 
         public override void BeforeRead(ResourcePipeline pipeline, bool isIncluded = false, string stringId = null)
         {

src/JsonApiDotNetCore/Configuration/JsonApiApplicationBuilder.cs

@@ -46,7 +46,7 @@ public JsonApiApplicationBuilder(IServiceCollection services, IMvcCoreBuilder mv
             var loggerFactory = _intermediateProvider.GetService<ILoggerFactory>();
 
             _resourceGraphBuilder = new ResourceGraphBuilder(_options, loggerFactory);
-            _serviceDiscoveryFacade = new ServiceDiscoveryFacade(_services, _resourceGraphBuilder, loggerFactory);
+            _serviceDiscoveryFacade = new ServiceDiscoveryFacade(_services, _resourceGraphBuilder, _options, loggerFactory);
         }
 
         /// <summary>
@@ -114,7 +114,7 @@ public void DiscoverInjectables()
         /// <summary>
         /// Registers the remaining internals.
         /// </summary>
-        public void ConfigureServices(Type dbContextType)
+        public void ConfigureServiceContainer(Type dbContextType)
         {
             if (dbContextType != null)
             {
@@ -127,28 +127,23 @@ public void ConfigureServices(Type dbContextType)
                 _services.AddSingleton(new DbContextOptionsBuilder().Options);
             }
 
+            AddResourceLayer();
             AddRepositoryLayer();
             AddServiceLayer();
             AddMiddlewareLayer();
+            AddSerializationLayer();
+            AddQueryStringLayer();
 
-            _services.AddSingleton<IResourceContextProvider>(sp => sp.GetRequiredService<IResourceGraph>());
-            
-            _services.AddScoped<IGenericServiceFactory, GenericServiceFactory>();
-            _services.AddScoped(typeof(RepositoryRelationshipUpdateHelper<>));
-            _services.AddScoped<IResourceDefinitionProvider, ResourceDefinitionProvider>();
-            _services.AddScoped(typeof(IResourceChangeTracker<>), typeof(ResourceChangeTracker<>));
-            _services.AddScoped<IResourceFactory, ResourceFactory>();
-            _services.AddScoped<IPaginationContext, PaginationContext>();
-            _services.AddScoped<IQueryLayerComposer, QueryLayerComposer>();
-
-            AddServerSerialization();
-            AddQueryStringParameterServices();
-            
             if (_options.EnableResourceHooks)
             {
                 AddResourceHooks();
             }
 
+            _services.AddScoped<IGenericServiceFactory, GenericServiceFactory>();
+            _services.AddScoped(typeof(RepositoryRelationshipUpdateHelper<>));
+            _services.AddScoped(typeof(IResourceChangeTracker<>), typeof(ResourceChangeTracker<>));
+            _services.AddScoped<IPaginationContext, PaginationContext>();
+            _services.AddScoped<IQueryLayerComposer, QueryLayerComposer>();
             _services.TryAddScoped<IInverseRelationships, InverseRelationships>();
         }
 
@@ -173,6 +168,17 @@ private void AddMiddlewareLayer()
             _services.AddScoped<IFieldsToSerialize, FieldsToSerialize>();
         }
 
+        private void AddResourceLayer()
+        {
+            _services.AddScoped(typeof(IResourceDefinition<>), typeof(JsonApiResourceDefinition<>));
+            _services.AddScoped(typeof(IResourceDefinition<,>), typeof(JsonApiResourceDefinition<,>));
+            _services.AddScoped<IResourceDefinitionAccessor, ResourceDefinitionAccessor>();
+
+            _services.AddScoped<IResourceFactory, ResourceFactory>();
+
+            _services.AddSingleton<IResourceContextProvider>(sp => sp.GetRequiredService<IResourceGraph>());
+        }
+
         private void AddRepositoryLayer()
         {
             _services.AddScoped(typeof(IResourceRepository<>), typeof(EntityFrameworkCoreRepository<>));
@@ -208,11 +214,14 @@ private void AddServiceLayer()
             _services.AddScoped(typeof(IResourceService<>), typeof(JsonApiResourceService<>));
             _services.AddScoped(typeof(IResourceService<,>), typeof(JsonApiResourceService<,>));
 
+            _services.AddScoped(typeof(IResourceQueryService<>), typeof(JsonApiResourceService<>));
             _services.AddScoped(typeof(IResourceQueryService<,>), typeof(JsonApiResourceService<,>));
+            
+            _services.AddScoped(typeof(IResourceCommandService<>), typeof(JsonApiResourceService<>));
             _services.AddScoped(typeof(IResourceCommandService<,>), typeof(JsonApiResourceService<,>));
         }
 
-        private void AddQueryStringParameterServices()
+        private void AddQueryStringLayer()
         {
             _services.AddScoped<IIncludeQueryStringParameterReader, IncludeQueryStringParameterReader>();
             _services.AddScoped<IFilterQueryStringParameterReader, FilterQueryStringParameterReader>();
@@ -246,13 +255,13 @@ private void AddQueryStringParameterServices()
         private void AddResourceHooks()
         {
             _services.AddSingleton(typeof(IHooksDiscovery<>), typeof(HooksDiscovery<>));
-            _services.AddScoped(typeof(IResourceHookContainer<>), typeof(ResourceDefinition<>));
+            _services.AddScoped(typeof(IResourceHookContainer<>), typeof(ResourceHooksDefinition<>));
             _services.AddTransient(typeof(IResourceHookExecutor), typeof(ResourceHookExecutor));
             _services.AddTransient<IHookExecutorHelper, HookExecutorHelper>();
             _services.AddTransient<ITraversalHelper, TraversalHelper>();
         }
 
-        private void AddServerSerialization()
+        private void AddSerializationLayer()
         {
             _services.AddScoped<IIncludedResourceObjectBuilder, IncludedResourceObjectBuilder>();
             _services.AddScoped<IJsonApiDeserializer, RequestDeserializer>();

src/JsonApiDotNetCore/Configuration/ResourceContext.cs

@@ -1,7 +1,6 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
-using JsonApiDotNetCore.Resources;
 using JsonApiDotNetCore.Resources.Annotations;
 
 namespace JsonApiDotNetCore.Configuration
@@ -26,12 +25,6 @@ public class ResourceContext
         /// </summary>
         public Type IdentityType { get; set; }
 
-        /// <summary>
-        /// The concrete <see cref="ResourceDefinition{TResource}"/> type.
-        /// We store this so that we don't need to re-compute the generic type.
-        /// </summary>
-        public Type ResourceDefinitionType { get; set; }
-
         /// <summary>
         /// Exposed resource attributes.
         /// See https://jsonapi.org/format/#document-resource-object-attributes.