feat(api-v2): Return value UUID on value creation and update (#1602)

docs/src/paradox/03-apis/api-v2/editing-values.md

@@ -94,8 +94,12 @@ If permissions are not given, configurable default permissions are used
 
 To create a value, the user must have **modify permission** on the containing resource.
 
-The response is a JSON-LD document containing only `@id` and `@type`, returning the IRI
-and type of the value that was created.
+The response is a JSON-LD document containing:
+
+- `@id`: the IRI of the value that was created.
+- `@type`: the value's type.
+- `knora-api:valueHasUUID`, the value's UUID, which remains stable across value versions
+  (except for link values, as explained below).
 
 ### Creating a Link Between Resources
 
@@ -127,6 +131,15 @@ we can create a link like this:
 
 As with ordinary values, permissions on links can be specified by adding `knora-api:hasPermissions`.
 
+The response is a JSON-LD document containing:
+
+- `@id`: the IRI of the value that was created.
+- `@type`: the value's type.
+- `knora-api:valueHasUUID`, the value's UUID, which remains stable across value versions,
+  unless the link is changed to point to a different resource, in which case it is
+  considered a new link and gets a new UUID. Changing a link's metadata, without
+  changing its target, creates a new version of the link value with the same UUID.
+
 ### Creating a Text Value Without Standoff Markup
 
 Use the predicate `knora-api:valueAsString` of `knora-api:TextValue`:
@@ -357,6 +370,14 @@ and type of the new value version.
 If you submit an outdated value ID in a request to update a value, the response will be
 an HTTP 404 (Not Found) error.
 
+The response to a value update request contains:
+
+- `@id`: the IRI of the value that was created.
+- `@type`: the value's type.
+- `knora-api:valueHasUUID`, the value's UUID, which remains stable across value versions,
+  unless the value is a link value and is changed to point to a different resource, in which
+  case it is considered a new link and gets a new UUID.
+
 ## Deleting a Value
 
 Knora does not normally delete values; instead, it marks them as deleted, which means

webapi/src/main/scala/org/knora/webapi/SharedTestDataADM.scala

@@ -21,6 +21,7 @@ package org.knora.webapi
 
 import java.net.URLEncoder
 import java.time.Instant
+import java.util.UUID
 
 import org.knora.webapi.SharedOntologyTestDataADM._
 import org.knora.webapi.messages.admin.responder.groupsmessages.GroupADM
@@ -1899,4 +1900,7 @@ object SharedTestDataADM {
     val treeListNode: IRI = "http://rdfh.ch/lists/0001/treeList01"
 
     val otherTreeList: IRI = "http://rdfh.ch/lists/0001/otherTreeList"
+
+    val testResponseValueIri: IRI = "http://rdfh.ch/0001/_GlNQXdYRTyQPhpdh76U1w/values/OGbYaSgNSUCKQtmn9suXlw"
+    val testResponseValueUUID: UUID = UUID.fromString("84a3af57-ee99-486f-aa9c-e4ca1d19a57d")
 }

webapi/src/main/scala/org/knora/webapi/routing/v2/ValuesRouteV2.scala

@@ -358,6 +358,26 @@ class ValuesRouteV2(routeData: KnoraRouteData) extends KnoraRoute(routeData) wit
         )
     }
 
+    private def createValueTestResponse: Future[SourceCodeFileContent] = {
+        val createValueResponseV2: CreateValueResponseV2 = CreateValueResponseV2(
+            valueIri = SharedTestDataADM.testResponseValueIri,
+            valueType = OntologyConstants.KnoraApiV2Complex.IntValue.toSmartIri,
+            valueUUID = SharedTestDataADM.testResponseValueUUID,
+            projectADM = SharedTestDataADM.anythingProject
+        )
+
+        Future {
+            SourceCodeFileContent(
+                filePath = SourceCodeFilePath.makeJsonPath("create-value-response"),
+                text = createValueResponseV2.toJsonLDDocument(
+                    targetSchema = ApiV2Complex,
+                    settings = settings,
+                    schemaOptions = Set.empty
+                ).toPrettyString
+            )
+        }
+    }
+
     private def updateValue: Route = path(ValuesBasePath) {
         put {
             entity(as[String]) { jsonRequest =>
@@ -583,6 +603,26 @@ class ValuesRouteV2(routeData: KnoraRouteData) extends KnoraRoute(routeData) wit
         )
     }
 
+    private def updateValueTestResponse: Future[SourceCodeFileContent] = {
+        val createValueResponseV2: UpdateValueResponseV2 = UpdateValueResponseV2(
+            valueIri = SharedTestDataADM.testResponseValueIri,
+            valueType = OntologyConstants.KnoraApiV2Complex.IntValue.toSmartIri,
+            valueUUID = SharedTestDataADM.testResponseValueUUID,
+            projectADM = SharedTestDataADM.anythingProject
+        )
+
+        Future {
+            SourceCodeFileContent(
+                filePath = SourceCodeFilePath.makeJsonPath("update-value-response"),
+                text = createValueResponseV2.toJsonLDDocument(
+                    targetSchema = ApiV2Complex,
+                    settings = settings,
+                    schemaOptions = Set.empty
+                ).toPrettyString
+            )
+        }
+    }
+
     private def deleteValue: Route = path(ValuesBasePath / "delete") {
         post {
             entity(as[String]) { jsonRequest =>
@@ -647,6 +687,8 @@ class ValuesRouteV2(routeData: KnoraRouteData) extends KnoraRoute(routeData) wit
             createRequests: Set[SourceCodeFileContent] <- createValueTestRequests
             updateRequests: Set[SourceCodeFileContent] <- updateValueTestRequests
             deleteRequests: Set[SourceCodeFileContent] <- deleteValueTestRequests
-        } yield getResponses ++ createRequests ++ updateRequests ++ deleteRequests
+            createValueResponse: SourceCodeFileContent <- createValueTestResponse
+            updateValueResponse: SourceCodeFileContent <- updateValueTestResponse
+        } yield getResponses ++ createRequests ++ updateRequests ++ deleteRequests + createValueResponse + updateValueResponse
     }
 }