Basic plumbing of version through the pipeline

Author: Bart Koelman

Diff for: src/JsonApiDotNetCore/Configuration/ResourceType.cs

@@ -2,6 +2,7 @@
 using System.Collections.Generic;
 using System.Linq;
 using JetBrains.Annotations;
+using JsonApiDotNetCore.Resources;
 using JsonApiDotNetCore.Resources.Annotations;
 
 namespace JsonApiDotNetCore.Configuration
@@ -30,6 +31,11 @@ public sealed class ResourceType
         /// </summary>
         public Type IdentityClrType { get; }
 
+        /// <summary>
+        /// When <c>true</c>, this resource type uses optimistic concurrency.
+        /// </summary>
+        public bool IsVersioned => ClrType.IsOrImplementsInterface<IVersionedIdentifiable>();
+
         /// <summary>
         /// Exposed resource attributes and relationships. See https://jsonapi.org/format/#document-resource-object-fields.
         /// </summary>

Diff for: src/JsonApiDotNetCore/Controllers/BaseJsonApiController.cs

@@ -210,8 +210,9 @@ public virtual async Task<IActionResult> PostAsync([FromBody] TResource resource
 
             TResource? newResource = await _create.CreateAsync(resource, cancellationToken);
 
-            string resourceId = (newResource ?? resource).StringId!;
-            string locationUrl = $"{HttpContext.Request.Path}/{resourceId}";
+            TResource resultResource = newResource ?? resource;
+            string? resourceVersion = resultResource.GetVersion();
+            string locationUrl = $"{HttpContext.Request.Path}/{resultResource.StringId}{(resourceVersion != null ? $";v~{resourceVersion}" : null)}";
 
             if (newResource == null)
             {
@@ -225,6 +226,9 @@ public virtual async Task<IActionResult> PostAsync([FromBody] TResource resource
         /// <summary>
         /// Adds resources to a to-many relationship. Example: <code><![CDATA[
         /// POST /articles/1/revisions HTTP/1.1
+        /// ]]></code> Example:
+        /// <code><![CDATA[
+        /// POST /articles/1;v~8/revisions HTTP/1.1
         /// ]]></code>
         /// </summary>
         /// <param name="id">
@@ -266,6 +270,9 @@ public virtual async Task<IActionResult> PostRelationshipAsync(TId id, string re
         /// Updates the attributes and/or relationships of an existing resource. Only the values of sent attributes are replaced. And only the values of sent
         /// relationships are replaced. Example: <code><![CDATA[
         /// PATCH /articles/1 HTTP/1.1
+        /// ]]></code> Example:
+        /// <code><![CDATA[
+        /// PATCH /articles/1;v~8 HTTP/1.1
         /// ]]></code>
         /// </summary>
         public virtual async Task<IActionResult> PatchAsync(TId id, [FromBody] TResource resource, CancellationToken cancellationToken)
@@ -299,7 +306,13 @@ public virtual async Task<IActionResult> PatchAsync(TId id, [FromBody] TResource
         /// PATCH /articles/1/relationships/author HTTP/1.1
         /// ]]></code> Example:
         /// <code><![CDATA[
+        /// PATCH /articles/1;v~8/relationships/author HTTP/1.1
+        /// ]]></code> Example:
+        /// <code><![CDATA[
         /// PATCH /articles/1/relationships/revisions HTTP/1.1
+        /// ]]></code> Example:
+        /// <code><![CDATA[
+        /// PATCH /articles/1;v~8/relationships/revisions HTTP/1.1
         /// ]]></code>
         /// </summary>
         /// <param name="id">
@@ -339,6 +352,9 @@ public virtual async Task<IActionResult> PatchRelationshipAsync(TId id, string r
         /// <summary>
         /// Deletes an existing resource. Example: <code><![CDATA[
         /// DELETE /articles/1 HTTP/1.1
+        /// ]]></code> Example:
+        /// <code><![CDATA[
+        /// DELETE /articles/1;v~8 HTTP/1.1
         /// ]]></code>
         /// </summary>
         public virtual async Task<IActionResult> DeleteAsync(TId id, CancellationToken cancellationToken)
@@ -361,6 +377,9 @@ public virtual async Task<IActionResult> DeleteAsync(TId id, CancellationToken c
         /// <summary>
         /// Removes resources from a to-many relationship. Example: <code><![CDATA[
         /// DELETE /articles/1/relationships/revisions HTTP/1.1
+        /// ]]></code> Example:
+        /// <code><![CDATA[
+        /// DELETE /articles/1;v~8/relationships/revisions HTTP/1.1
         /// ]]></code>
         /// </summary>
         /// <param name="id">

Diff for: src/JsonApiDotNetCore/Controllers/JsonApiController.cs

@@ -50,14 +50,18 @@ public override async Task<IActionResult> GetAsync(CancellationToken cancellatio
         }
 
         /// <inheritdoc />
+        // The {version} parameter is allowed, but ignored. It occurs in rendered links, because POST/PATCH/DELETE use it.
         [HttpGet("{id}")]
+        [HttpGet("{id};v~{version}")]
         [HttpHead("{id}")]
+        [HttpHead("{id};v~{version}")]
         public override async Task<IActionResult> GetAsync(TId id, CancellationToken cancellationToken)
         {
             return await base.GetAsync(id, cancellationToken);
         }
 
         /// <inheritdoc />
+        // No {version} parameter, because it does not occur in rendered links.
         [HttpGet("{id}/{relationshipName}")]
         [HttpHead("{id}/{relationshipName}")]
         public override async Task<IActionResult> GetSecondaryAsync(TId id, string relationshipName, CancellationToken cancellationToken)
@@ -66,8 +70,11 @@ public override async Task<IActionResult> GetSecondaryAsync(TId id, string relat
         }
 
         /// <inheritdoc />
+        // The {version} parameter is allowed, but ignored. It occurs in rendered links, because POST/PATCH/DELETE use it.
         [HttpGet("{id}/relationships/{relationshipName}")]
+        [HttpGet("{id};v~{version}/relationships/{relationshipName}")]
         [HttpHead("{id}/relationships/{relationshipName}")]
+        [HttpHead("{id};v~{version}/relationships/{relationshipName}")]
         public override async Task<IActionResult> GetRelationshipAsync(TId id, string relationshipName, CancellationToken cancellationToken)
         {
             return await base.GetRelationshipAsync(id, relationshipName, cancellationToken);
@@ -82,6 +89,7 @@ public override async Task<IActionResult> PostAsync([FromBody] TResource resourc
 
         /// <inheritdoc />
         [HttpPost("{id}/relationships/{relationshipName}")]
+        [HttpPost("{id};v~{version}/relationships/{relationshipName}")]
         public override async Task<IActionResult> PostRelationshipAsync(TId id, string relationshipName, [FromBody] ISet<IIdentifiable> rightResourceIds,
             CancellationToken cancellationToken)
         {
@@ -90,13 +98,15 @@ public override async Task<IActionResult> PostRelationshipAsync(TId id, string r
 
         /// <inheritdoc />
         [HttpPatch("{id}")]
+        [HttpPatch("{id};v~{version}")]
         public override async Task<IActionResult> PatchAsync(TId id, [FromBody] TResource resource, CancellationToken cancellationToken)
         {
             return await base.PatchAsync(id, resource, cancellationToken);
         }
 
         /// <inheritdoc />
         [HttpPatch("{id}/relationships/{relationshipName}")]
+        [HttpPatch("{id};v~{version}/relationships/{relationshipName}")]
         public override async Task<IActionResult> PatchRelationshipAsync(TId id, string relationshipName, [FromBody] object? rightValue,
             CancellationToken cancellationToken)
         {
@@ -105,13 +115,15 @@ public override async Task<IActionResult> PatchRelationshipAsync(TId id, string
 
         /// <inheritdoc />
         [HttpDelete("{id}")]
+        [HttpDelete("{id};v~{version}")]
         public override async Task<IActionResult> DeleteAsync(TId id, CancellationToken cancellationToken)
         {
             return await base.DeleteAsync(id, cancellationToken);
         }
 
         /// <inheritdoc />
         [HttpDelete("{id}/relationships/{relationshipName}")]
+        [HttpDelete("{id};v~{version}/relationships/{relationshipName}")]
         public override async Task<IActionResult> DeleteRelationshipAsync(TId id, string relationshipName, [FromBody] ISet<IIdentifiable> rightResourceIds,
             CancellationToken cancellationToken)
         {

Diff for: src/JsonApiDotNetCore/Middleware/IJsonApiRequest.cs

@@ -19,6 +19,12 @@ public interface IJsonApiRequest
         /// </summary>
         string? PrimaryId { get; }
 
+        /// <summary>
+        /// The version of the primary resource for this request, when using optimistic concurrency. This would be "abc" in "/blogs/123;v~abc/author". This is
+        /// <c>null</c> when not using optimistic concurrency, and before and after processing operations in an atomic:operations request.
+        /// </summary>
+        string? PrimaryVersion { get; }
+
         /// <summary>
         /// The primary resource type for this request. This would be "blogs" in "/blogs", "/blogs/123" or "/blogs/123/author". This is <c>null</c> before and
         /// after processing operations in an atomic:operations request.

Diff for: src/JsonApiDotNetCore/Middleware/JsonApiMiddleware.cs

@@ -226,6 +226,7 @@ private static void SetupResourceRequest(JsonApiRequest request, ResourceType pr
             request.IsReadOnly = httpRequest.Method == HttpMethod.Get.Method || httpRequest.Method == HttpMethod.Head.Method;
             request.PrimaryResourceType = primaryResourceType;
             request.PrimaryId = GetPrimaryRequestId(routeValues);
+            request.PrimaryVersion = GetPrimaryRequestVersion(routeValues);
 
             string? relationshipName = GetRelationshipNameForSecondaryRequest(routeValues);
 
@@ -277,6 +278,11 @@ private static void SetupResourceRequest(JsonApiRequest request, ResourceType pr
             return routeValues.TryGetValue("id", out object? id) ? (string?)id : null;
         }
 
+        private static string? GetPrimaryRequestVersion(RouteValueDictionary routeValues)
+        {
+            return routeValues.TryGetValue("version", out object? id) ? (string?)id : null;
+        }
+
         private static string? GetRelationshipNameForSecondaryRequest(RouteValueDictionary routeValues)
         {
             return routeValues.TryGetValue("relationshipName", out object? routeValue) ? (string?)routeValue : null;

Diff for: src/JsonApiDotNetCore/Middleware/JsonApiRequest.cs

@@ -14,6 +14,9 @@ public sealed class JsonApiRequest : IJsonApiRequest
         /// <inheritdoc />
         public string? PrimaryId { get; set; }
 
+        /// <inheritdoc />
+        public string? PrimaryVersion { get; set; }
+
         /// <inheritdoc />
         public ResourceType? PrimaryResourceType { get; set; }
 
@@ -42,6 +45,7 @@ public void CopyFrom(IJsonApiRequest other)
 
             Kind = other.Kind;
             PrimaryId = other.PrimaryId;
+            PrimaryVersion = other.PrimaryVersion;
             PrimaryResourceType = other.PrimaryResourceType;
             SecondaryResourceType = other.SecondaryResourceType;
             Relationship = other.Relationship;

Diff for: src/JsonApiDotNetCore/Resources/IVersionedIdentifiable.cs

@@ -0,0 +1,31 @@
+namespace JsonApiDotNetCore.Resources
+{
+    /// <summary>
+    /// Defines the basic contract for a JSON:API resource that uses optimistic concurrency. All resource classes must implement
+    /// <see cref="IVersionedIdentifiable{TId, TVersion}" />.
+    /// </summary>
+    public interface IVersionedIdentifiable : IIdentifiable
+    {
+        /// <summary>
+        /// The value for element 'version' in a JSON:API request or response.
+        /// </summary>
+        string? Version { get; set; }
+    }
+
+    /// <summary>
+    /// When implemented by a class, indicates to JsonApiDotNetCore that the class represents a JSON:API resource that uses optimistic concurrency.
+    /// </summary>
+    /// <typeparam name="TId">
+    /// The resource identifier type.
+    /// </typeparam>
+    /// <typeparam name="TVersion">
+    /// The database vendor-specific type that is used to store the concurrency token.
+    /// </typeparam>
+    public interface IVersionedIdentifiable<TId, TVersion> : IIdentifiable<TId>, IVersionedIdentifiable
+    {
+        /// <summary>
+        /// The concurrency token, which is used to detect if the resource was modified by another user since the moment this resource was last retrieved.
+        /// </summary>
+        TVersion ConcurrencyToken { get; set; }
+    }
+}

Diff for: src/JsonApiDotNetCore/Resources/IdentifiableExtensions.cs

@@ -35,5 +35,22 @@ public static object GetTypedId(this IIdentifiable identifiable)
 
             return propertyValue!;
         }
+
+        public static string? GetVersion(this IIdentifiable identifiable)
+        {
+            ArgumentGuard.NotNull(identifiable, nameof(identifiable));
+
+            return identifiable is IVersionedIdentifiable versionedIdentifiable ? versionedIdentifiable.Version : null;
+        }
+
+        public static void SetVersion(this IIdentifiable identifiable, string? version)
+        {
+            ArgumentGuard.NotNull(identifiable, nameof(identifiable));
+
+            if (identifiable is IVersionedIdentifiable versionedIdentifiable)
+            {
+                versionedIdentifiable.Version = version;
+            }
+        }
     }
 }

Diff for: src/JsonApiDotNetCore/Serialization/JsonConverters/ResourceObjectConverter.cs

@@ -20,6 +20,7 @@ public sealed class ResourceObjectConverter : JsonObjectConverter<ResourceObject
         private static readonly JsonEncodedText TypeText = JsonEncodedText.Encode("type");
         private static readonly JsonEncodedText IdText = JsonEncodedText.Encode("id");
         private static readonly JsonEncodedText LidText = JsonEncodedText.Encode("lid");
+        private static readonly JsonEncodedText VersionText = JsonEncodedText.Encode("version");
         private static readonly JsonEncodedText MetaText = JsonEncodedText.Encode("meta");
         private static readonly JsonEncodedText AttributesText = JsonEncodedText.Encode("attributes");
         private static readonly JsonEncodedText RelationshipsText = JsonEncodedText.Encode("relationships");
@@ -86,6 +87,11 @@ public override ResourceObject Read(ref Utf8JsonReader reader, Type typeToConver
                                 resourceObject.Lid = reader.GetString();
                                 break;
                             }
+                            case "version":
+                            {
+                                resourceObject.Version = reader.GetString();
+                                break;
+                            }
                             case "attributes":
                             {
                                 if (resourceType != null)
@@ -240,6 +246,11 @@ public override void Write(Utf8JsonWriter writer, ResourceObject value, JsonSeri
                 writer.WriteString(LidText, value.Lid);
             }
 
+            if (value.Version != null)
+            {
+                writer.WriteString(VersionText, value.Version);
+            }
+
             if (!value.Attributes.IsNullOrEmpty())
             {
                 writer.WritePropertyName(AttributesText);

Diff for: src/JsonApiDotNetCore/Serialization/Objects/AtomicReference.cs

@@ -21,6 +21,10 @@ public sealed class AtomicReference : IResourceIdentity
         [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
         public string? Lid { get; set; }
 
+        [JsonPropertyName("version")]
+        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+        public string? Version { get; set; }
+
         [JsonPropertyName("relationship")]
         [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
         public string? Relationship { get; set; }

Diff for: src/JsonApiDotNetCore/Serialization/Objects/IResourceIdentity.cs

@@ -5,5 +5,6 @@ public interface IResourceIdentity
         public string? Type { get; }
         public string? Id { get; }
         public string? Lid { get; }
+        public string? Version { get; }
     }
 }

Diff for: src/JsonApiDotNetCore/Serialization/Objects/ResourceIdentifierObject.cs

@@ -22,6 +22,10 @@ public sealed class ResourceIdentifierObject : IResourceIdentity
         [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
         public string? Lid { get; set; }
 
+        [JsonPropertyName("version")]
+        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+        public string? Version { get; set; }
+
         [JsonPropertyName("meta")]
         [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
         public IDictionary<string, object?>? Meta { get; set; }

Diff for: src/JsonApiDotNetCore/Serialization/Objects/ResourceObject.cs

@@ -22,6 +22,10 @@ public sealed class ResourceObject : IResourceIdentity
         [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
         public string? Lid { get; set; }
 
+        [JsonPropertyName("version")]
+        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+        public string? Version { get; set; }
+
         [JsonPropertyName("attributes")]
         [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
         public IDictionary<string, object?>? Attributes { get; set; }

Diff for: src/JsonApiDotNetCore/Serialization/Request/Adapters/AtomicOperationObjectAdapter.cs

@@ -111,6 +111,7 @@ private WriteOperationKind ConvertOperationCode(AtomicOperationObject atomicOper
             if (refResult != null)
             {
                 state.WritableRequest!.PrimaryId = refResult.Resource.StringId;
+                state.WritableRequest.PrimaryVersion = refResult.Resource.GetVersion();
                 state.WritableRequest.PrimaryResourceType = refResult.ResourceType;
                 state.WritableRequest.Relationship = refResult.Relationship;
                 state.WritableRequest.IsCollection = refResult.Relationship is HasManyAttribute;

Diff for: src/JsonApiDotNetCore/Serialization/Request/Adapters/RelationshipDataAdapter.cs

@@ -44,7 +44,8 @@ private static SingleOrManyData<ResourceIdentifierObject> ToIdentifierData(Singl
                 {
                     Type = resourceObject.Type,
                     Id = resourceObject.Id,
-                    Lid = resourceObject.Lid
+                    Lid = resourceObject.Lid,
+                    Version = resourceObject.Version
                 });
             }
             else if (data.SingleValue != null)
@@ -53,7 +54,8 @@ private static SingleOrManyData<ResourceIdentifierObject> ToIdentifierData(Singl
                 {
                     Type = data.SingleValue.Type,
                     Id = data.SingleValue.Id,
-                    Lid = data.SingleValue.Lid
+                    Lid = data.SingleValue.Lid,
+                    Version = data.SingleValue.Version
                 };
             }
 

Diff for: src/JsonApiDotNetCore/Serialization/Request/Adapters/ResourceDataInOperationsRequestAdapter.cs

@@ -21,6 +21,7 @@ protected override (IIdentifiable resource, ResourceType resourceType) ConvertRe
 
             state.WritableRequest!.PrimaryResourceType = resourceType;
             state.WritableRequest.PrimaryId = resource.StringId;
+            state.WritableRequest.PrimaryVersion = resource.GetVersion();
 
             return (resource, resourceType);
         }

Diff for: src/JsonApiDotNetCore/Serialization/Request/Adapters/ResourceIdentityAdapter.cs

@@ -105,6 +105,8 @@ private IIdentifiable CreateResource(IResourceIdentity identity, ResourceIdentit
             IIdentifiable resource = _resourceFactory.CreateInstance(resourceClrType);
             AssignStringId(identity, resource, state);
             resource.LocalId = identity.Lid;
+            resource.SetVersion(identity.Version);
+
             return resource;
         }