feat(resourceHistoryEvents): route for resource history events (DSP-1749)

docs/03-apis/api-v2/reading-and-searching-resources.md

@@ -571,22 +571,26 @@ be sorted alphabetically by resource IRI (an arbitrary but consistent order).
 The value of `page` is a 0-based integer page number. Paging works as it does
 in [Gravsearch](query-language.md)).
 
-### Get the Version History of Resources and Values of a Project
+### Get the Full History of a Resource and its Values as Events
 
-To get a list of the changes that have been made to resources and values of a project since their creation ordered by date
-use this route:
+To get a list of the changes that have been made to a resource and its values since its creation as events ordered by 
+date:
 
 ```
-HTTP GET to http://host/v2/resources/projectHistory/projectIRI
+HTTP GET to http://host/v2/resources/resourceHistoryEvents/<resourceIRI>
 ```
 
-The project IRI must be URL-encoded. The response is a list of events describing changes made to the resource and its values,
+The resource IRI must be URL-encoded. The response is a list of events describing changes made to the resource and its values,
  in chronological order. Each entry has the properties: 
  `knora-api:eventType` (the type of the operation performed on a specific date. The operation can be either
- `createResource`, `deleteResource`, `createValue`, `updateValueContent`, `updateValuePermissions`, or `deleteValue`.), 
+ `createResource`, `updateResourceMetadata`, `deleteResource`, `createValue`, `updateValueContent`, `updateValuePermissions`, 
+  or `deleteValue`.), 
 `knora-api:versionDate` (the date when the change was made),
 `knora-api:author` (the IRI of the user who made the change),
-`knora-api:eventBody` (the information necessary to make the same request). For example:
+`knora-api:eventBody` (the information necessary to make the same request). 
+
+For example, the following response contains the list of events describing the version history of the resource 
+`http://rdfh.ch/0001/thing-with-history` ordered by date:
 
 ```jsonld
 {
@@ -699,4 +703,25 @@ The project IRI must be URL-encoded. The response is a list of events describing
     "knora-api" : "http://api.knora.org/ontology/knora-api/v2#"
   }
 }
-```
+```
+
+Since the history of changes made to the metadata of a resource is not part of resouce's version history, there are no 
+events describing the changes on metadata elements like its `rdfs:label` or `rdfs:comment`. 
+The only record depicting a change in a resource's metadata is the `knora-api:lastModificationDate` of the resource. Thus 
+the event `updateResourceMetadat` indicates a change in a resource's metadata, its `knora-api:eventBody` contains the 
+payload needed to update the value of the resource's `lastModificationDate`, see 
+[modifying metadata of a resource](editing-resources.md#modifying-a-resources-metadata).
+
+
+
+### Get the Full History of all Resources of a Project as Events
+
+To get a list of the changes that have been made to the resources and their values of a project as events ordered by 
+date:
+
+```
+HTTP GET to http://host/v2/resources/projectHistoryEvents/<projectIRI>
+```
+
+The project IRI must be URL-encoded. The response contains the resource history events of all resources that belong to 
+the specified project.

webapi/src/main/scala/org/knora/webapi/messages/v2/responder/resourcemessages/ResourceMessagesV2.scala

@@ -148,15 +148,16 @@ case class ResourceVersionHistoryGetRequestV2(resourceIri: IRI,
   * Requests the full version history of a resource and its values as events.
   *
   * @param resourceIri            the IRI of the resource.
-  * @param resourceVersionHistory the version history of the resource and its values.
   * @param featureFactoryConfig   the feature factory configuration.
   * @param requestingUser         the user making the request.
   */
-case class ResourceFullHistoryGetRequestV2(resourceIri: IRI,
-                                           resourceVersionHistory: Seq[ResourceHistoryEntry],
-                                           featureFactoryConfig: FeatureFactoryConfig,
-                                           requestingUser: UserADM)
-    extends ResourcesResponderRequestV2
+case class ResourceHistoryEventsGetRequestV2(resourceIri: IRI,
+                                             featureFactoryConfig: FeatureFactoryConfig,
+                                             requestingUser: UserADM)
+    extends ResourcesResponderRequestV2 {
+  private val stringFormatter = StringFormatter.getInstanceForConstantOntologies
+  stringFormatter.validateAndEscapeIri(resourceIri, throw BadRequestException(s"Invalid resource IRI: $resourceIri"))
+}
 
 /**
   * Requests the version history of all resources of a project.
@@ -1330,18 +1331,18 @@ case class GraphDataGetResponseV2(nodes: Seq[GraphNodeV2], edges: Seq[GraphEdgeV
 }
 
 /**
-  * Represents the version history of a resource or a values as events.
+  * Represents the version history of a resource or a value as events.
   *
   * @param eventType    the type of the operation that is one of [[ResourceAndValueEventsUtil]]
   * @param versionDate  the version date of the event.
   * @param author       the user which had performed the operation.
   * @param eventBody    the request body in the form of [[ResourceOrValueEventBody]] needed for the operation indicated
   *                     by eventType.
   */
-case class ResourceAndValueHistoryV2(eventType: String,
-                                     versionDate: Instant,
-                                     author: IRI,
-                                     eventBody: ResourceOrValueEventBody)
+case class ResourceAndValueHistoryEvent(eventType: String,
+                                        versionDate: Instant,
+                                        author: IRI,
+                                        eventBody: ResourceOrValueEventBody)
 
 abstract class ResourceOrValueEventBody
 
@@ -1549,9 +1550,9 @@ case class ValueEventBody(resourceIri: IRI,
 }
 
 /**
-  * Represents the history of the project resources and values.
+  * Represents the resource and value history events.
   */
-case class ResourceAndValueVersionHistoryResponseV2(projectHistory: Seq[ResourceAndValueHistoryV2])
+case class ResourceAndValueVersionHistoryResponseV2(historyEvents: Seq[ResourceAndValueHistoryEvent])
     extends KnoraJsonLDResponseV2 {
 
   /**
@@ -1571,7 +1572,7 @@ case class ResourceAndValueVersionHistoryResponseV2(projectHistory: Seq[Resource
 
     // Convert the history entries to an array of JSON-LD objects.
 
-    val projectHistoryAsJsonLD: Seq[JsonLDObject] = projectHistory.map { historyEntry: ResourceAndValueHistoryV2 =>
+    val historyEventsAsJsonLD: Seq[JsonLDObject] = historyEvents.map { historyEntry: ResourceAndValueHistoryEvent =>
       // convert event body to JsonLD object
       val eventBodyAsJsonLD: JsonLDObject = historyEntry.eventBody match {
         case valueEventBody: ValueEventBody => valueEventBody.toJsonLD(targetSchema, settings, schemaOptions)
@@ -1609,7 +1610,7 @@ case class ResourceAndValueVersionHistoryResponseV2(projectHistory: Seq[Resource
 
     // Make the JSON-LD document.
 
-    val body = JsonLDObject(Map(JsonLDKeywords.GRAPH -> JsonLDArray(projectHistoryAsJsonLD)))
+    val body = JsonLDObject(Map(JsonLDKeywords.GRAPH -> JsonLDArray(historyEventsAsJsonLD)))
 
     JsonLDDocument(body = body, context = context)
   }