put operation enabling behind a feature flag on global options

Author: jaredcnance

src/Examples/OperationsExample/Startup.cs

@@ -1,60 +1,61 @@
-using Microsoft.AspNetCore.Builder;
-using Microsoft.AspNetCore.Hosting;
-using Microsoft.Extensions.Configuration;
-using Microsoft.Extensions.DependencyInjection;
-using Microsoft.Extensions.Logging;
-using Microsoft.EntityFrameworkCore;
-using JsonApiDotNetCore.Extensions;
-using System;
-using OperationsExample.Data;
-using JsonApiDotNetCore.Models;
-
-namespace OperationsExample
-{
-    public class Startup
-    {
-        public readonly IConfiguration Config;
-
-        public Startup(IHostingEnvironment env)
-        {
-            var builder = new ConfigurationBuilder()
-                .SetBasePath(env.ContentRootPath)
-                .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
-                .AddEnvironmentVariables();
-
-            Config = builder.Build();
-        }
-
-        public virtual IServiceProvider ConfigureServices(IServiceCollection services)
-        {
-            var loggerFactory = new LoggerFactory();
-            loggerFactory
-              .AddConsole(LogLevel.Trace);
-            services.AddSingleton<ILoggerFactory>(loggerFactory);
-
-            services.AddDbContext<AppDbContext>(options =>
-            {
-                options.UseNpgsql(GetDbConnectionString());
-            }, ServiceLifetime.Transient);
-
-            services.AddJsonApi<AppDbContext>(opt => opt.EnableExtension(JsonApiExtension.Operations));
-
-            return services.BuildServiceProvider();
-        }
-
-        public virtual void Configure(
-            IApplicationBuilder app,
-            IHostingEnvironment env,
-            ILoggerFactory loggerFactory,
-            AppDbContext context)
-        {
-            context.Database.EnsureCreated();
-
-            loggerFactory.AddConsole(Config.GetSection("Logging"));
-            loggerFactory.AddDebug();
-            app.UseJsonApi();
-        }
-
-        public string GetDbConnectionString() => Config["Data:DefaultConnection"];
-    }
-}
+using System;
+using JsonApiDotNetCore.Extensions;
+using JsonApiDotNetCore.Models;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using OperationsExample.Data;
+
+
+namespace OperationsExample
+{
+    public class Startup
+    {
+        public readonly IConfiguration Config;
+
+        public Startup(IHostingEnvironment env)
+        {
+            var builder = new ConfigurationBuilder()
+                .SetBasePath(env.ContentRootPath)
+                .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
+                .AddEnvironmentVariables();
+
+            Config = builder.Build();
+        }
+
+        public virtual IServiceProvider ConfigureServices(IServiceCollection services)
+        {
+            var loggerFactory = new LoggerFactory();
+            loggerFactory.AddConsole(LogLevel.Trace);
+
+            services.AddSingleton<ILoggerFactory>(loggerFactory);
+
+            services.AddDbContext<AppDbContext>(options =>
+            {
+                options.UseNpgsql(GetDbConnectionString());
+            }, ServiceLifetime.Transient);
+
+            services.AddJsonApi<AppDbContext>(opt => opt.EnableOperations = true);
+
+            return services.BuildServiceProvider();
+        }
+
+        public virtual void Configure(
+            IApplicationBuilder app,
+            IHostingEnvironment env,
+            ILoggerFactory loggerFactory,
+            AppDbContext context)
+        {
+            context.Database.EnsureCreated();
+
+            loggerFactory.AddConsole(Config.GetSection("Logging"));
+            loggerFactory.AddDebug();
+            app.UseJsonApi();
+        }
+
+        public string GetDbConnectionString() => Config["Data:DefaultConnection"];
+    }
+}

src/JsonApiDotNetCore/Builders/DocumentBuilderOptionsProvider.cs

@@ -1,6 +1,3 @@
-using System;
-using System.Collections.Generic;
-using System.Text;
 using JsonApiDotNetCore.Services;
 using Microsoft.AspNetCore.Http;
 

src/JsonApiDotNetCore/Configuration/JsonApiOptions.cs

@@ -10,17 +10,106 @@
 
 namespace JsonApiDotNetCore.Configuration
 {
+    /// <summary>
+    /// Global options.
+    /// https://json-api-dotnet.github.io/#/global-options
+    /// </summary>
     public class JsonApiOptions
     {
+        /// <summary>
+        /// The base URL Namespace
+        /// </summary>
+        /// <example>
+        /// <code>options.Namespace = "api/v1";</code>
+        /// </example>
         public string Namespace { get; set; }
+
+        /// <summary>
+        /// The default page size for all resources
+        /// </summary>
+        /// <example>
+        /// <code>options.DefaultPageSize = 10;</code>
+        /// </example>
         public int DefaultPageSize { get; set; }
+
+        /// <summary>
+        /// Whether or not the total-record count should be included in all document
+        /// level meta objects.
+        /// Defaults to false.
+        /// </summary>
+        /// <example>
+        /// <code>options.IncludeTotalRecordCount = true;</code>
+        /// </example>
         public bool IncludeTotalRecordCount { get; set; }
+
+        /// <summary>
+        /// Whether or not clients can provide ids when creating resources.
+        /// Defaults to false.  When disabled the application will respond 
+        /// with a 403 Forbidden respponse if a client attempts to create a 
+        /// resource with a defined id.
+        /// </summary>
+        /// <example>
+        /// <code>options.AllowClientGeneratedIds = true;</code>
+        /// </example>
         public bool AllowClientGeneratedIds { get; set; }
+        
+        /// <summary>
+        /// The graph of all resources exposed by this application.
+        /// </summary>
         public IContextGraph ContextGraph { get; set; }
+
+        /// <summary>
+        /// Use relative links for all resources.
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// options.RelativeLinks = true;
+        /// </code>
+        /// <code>
+        /// {
+        ///   "type": "articles",
+        ///   "id": "4309",
+        ///   "relationships": {
+        ///      "author": {
+        ///        "links": {
+        ///          "self": "/api/v1/articles/4309/relationships/author",
+        ///          "related": "/api/v1/articles/4309/author"
+        ///        }
+        ///      }
+        ///   }
+        /// }
+        /// </code>
+        /// </example>
         public bool RelativeLinks { get; set; }
+
+        /// <summary>
+        /// Whether or not to allow all custom query parameters.
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// options.AllowCustomQueryParameters = true;
+        /// </code>
+        /// </example>
         public bool AllowCustomQueryParameters { get; set; }
+
+        /// <summary>
+        /// The default behavior for serializing null attributes.
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// options.NullAttributeResponseBehavior = new NullAttributeResponseBehavior {
+        ///  // ...
+        ///};
+        /// </code>
+        /// </example>
         public NullAttributeResponseBehavior NullAttributeResponseBehavior { get; set; }
 
+        /// <summary>
+        /// Whether or not to allow json:api v1.1 operation requests
+        /// This will be enabled by default in JsonApiDotNetCore v2.2.1
+        /// </summary>
+        public bool EnableOperations { get; set; }
+
         [Obsolete("JsonContract resolver can now be set on SerializerSettings.")]
         public IContractResolver JsonContractResolver
         {
@@ -33,9 +122,6 @@ public IContractResolver JsonContractResolver
             ContractResolver = new DasherizedResolver()
         };
 
-        internal IContextGraphBuilder ContextGraphBuilder { get; } = new ContextGraphBuilder();
-        internal List<JsonApiExtension> EnabledExtensions { get; set; } = new List<JsonApiExtension>();
-
         public void BuildContextGraph<TContext>(Action<IContextGraphBuilder> builder) where TContext : DbContext
         {
             BuildContextGraph(builder);
@@ -54,11 +140,10 @@ public void BuildContextGraph(Action<IContextGraphBuilder> builder)
             ContextGraph = ContextGraphBuilder.Build();
         }
 
-        public void EnableExtension(JsonApiExtension extension)
-        {
-            EnabledExtensions.Add(extension);
-        }
-    }
+        public void EnableExtension(JsonApiExtension extension) 
+            => EnabledExtensions.Add(extension);
 
-    
+        internal IContextGraphBuilder ContextGraphBuilder { get; } = new ContextGraphBuilder();
+        internal List<JsonApiExtension> EnabledExtensions { get; set; } = new List<JsonApiExtension>();
+    }
 }

src/JsonApiDotNetCore/Extensions/IServiceCollectionExtensions.cs

@@ -95,7 +95,7 @@ public static void AddJsonApiInternals(
                 services.AddSingleton<DbContextOptions>(new DbContextOptionsBuilder().Options);
             }
 
-            if (jsonApiOptions.EnabledExtensions.Contains(JsonApiExtension.Operations))
+            if (jsonApiOptions.EnableOperations)
                 AddOperationServices(services);
 
             services.AddScoped(typeof(IEntityRepository<>), typeof(DefaultEntityRepository<>));

src/JsonApiDotNetCore/Serialization/JsonApiDeSerializer.cs

@@ -29,11 +29,12 @@ public object Deserialize(string requestBody)
         {
             try
             {
-                // TODO: determine whether or not the token should be re-used rather than performing full
-                // deserialization again from the string
                 var bodyJToken = JToken.Parse(requestBody);
-                if(bodyJToken.SelectToken("operations") != null)
+
+                if(RequestIsOperation(bodyJToken))
                 {
+                    // TODO: determine whether or not the token should be re-used rather than performing full
+                    // deserialization again from the string
                     var operations = JsonConvert.DeserializeObject<OperationsDocument>(requestBody);
                     if (operations == null)
                         throw new JsonApiException(400, "Failed to deserialize operations request.");
@@ -53,6 +54,10 @@ public object Deserialize(string requestBody)
             }
         }
 
+        private bool RequestIsOperation(JToken bodyJToken) 
+            => _jsonApiContext.Options.EnableOperations 
+                && (bodyJToken.SelectToken("operations") != null);
+
         public TEntity Deserialize<TEntity>(string requestBody) => (TEntity)Deserialize(requestBody);
 
         public object DeserializeRelationship(string requestBody)