Merge branch 'DSpace:main' into main

DSpace · Feb 22, 2024 · 487f59b · 487f59b
2 parents 768e541 + 9deefd5
commit 487f59b
Show file tree

Hide file tree

Showing 10 changed files with 125 additions and 99 deletions.
diff --git a/authorizations.md b/authorizations.md
@@ -42,7 +42,7 @@ Return codes:
 
 The supported parameters are:
 * page, size [see pagination](README.md#Pagination)
-* uri: mandatory, the object to use for the authorization check. The full URI of the rest resource must be specified, i.e. https://{dspace.url}/api/core/community/{uuid}
+* uri: mandatory, the object to use for the authorization check. The full URI of the rest resource must be specified, i.e. https://{dspace.url}/api/core/communities/{uuid}
 * eperson: optional, the uuid of the eperson to evaluate for authorization. If not specified authorization of anonymous users will be returned
 * feature: optional, limit the returned authorization to the specified feature (this provide an alternative to codify the authorization id rule on the client side)
 
@@ -60,7 +60,7 @@ Return codes:
 The supported parameters are:
 * page, size [see pagination](README.md#Pagination)
 * uuid: mandatory, repeatable. Represents the list of objects to be used for the authorization check. For each of them, the UUID must be specified.2
-* type: mandatory. Represents the type of resource(s) (i.e. "core.item", "workflow.workflowitem",...)  on which authorizations are checked.
+* type: mandatory. Represents the type of resource(s) (i.e. "core.items", "workflow.workflowitems",...)  on which authorizations are checked.
 * eperson: optional, the uuid of the eperson to evaluate for authorization. If not specified authorization of anonymous users will be returned
 * feature: optional, repeatable. Represents the list of features. Limits the returned authorizations to the specified features (this provide an alternative to codify the authorization id rule on the client side)
 

diff --git a/endpoints.md b/endpoints.md
@@ -36,8 +36,8 @@
 * [/api/submission/vocabularies](vocabularies.md)
 * [/api/submission/vocabularyEntryDetails](vocabularyEntryDetails.md)
 * [/api/system/systemwidealerts](systemwidealerts.md)
-* [/api/versioning/version](version.md)
-* [/api/versioning/versionhistory](versionhistory.md)
+* [/api/versioning/versions](versions.md)
+* [/api/versioning/versionhistories](versionhistories.md)
 * [/api/workflow/workflowitems](workflowitems.md)
 * [/api/workflow/pooltasks](pooltasks.md)
 * [/api/workflow/claimedtasks](claimedtasks.md)

diff --git a/items.md b/items.md
@@ -526,7 +526,7 @@ Status codes:
 **GET /api/core/items/{:item-uuid}/version**
 
 Provide version information based on a given Item UUID. An Item UUID will only match one version. READ permissions over the item in addition to the version permissions are checked.
-The JSON response is the same as the [Version endpoint](version.md#get-single-version).
+The JSON response is the same as the [Version endpoint](versions.md#get-single-version).
 
 Return codes:
 * 200 OK - if the operation succeeds

diff --git a/search-rels.md b/search-rels.md
@@ -15,5 +15,5 @@ Search endpoints on a collection of resources should act as follows:
 * [/api/config/submissiondefinitions](submissiondefinitions.md)
 * [/api/submission/workspaceitems](workspaceitems.md)
 * [/api/workflow/claimedtasks](claimedtasks.md)
-* [/api/workflow/polltasks](polltasks.md)
+* [/api/workflow/pooltasks](pooltasks.md)
 * [/api/workflow/workflowitems](workflowitems.md)
diff --git a/statistics-reports.md b/statistics-reports.md
@@ -69,7 +69,7 @@ Possible response status
 This endpoint provides a paginated list of statistics for a DSpaceObject. 
 
 The DSpaceObject is given through the following parameters:
-- `uri` The object to retrieve statistics for. The full URI of the rest resource must be specified, i.e. https://{dspace.url}/server/api/core/community/{uuid}
+- `uri` The object to retrieve statistics for. The full URI of the rest resource must be specified, i.e. https://{dspace.url}/server/api/core/communities/{uuid}
 
 The usual parameters for paginated lists are supported as well:
 - `page` The page number 

diff --git a/submissionuploads.md b/submissionuploads.md
@@ -55,5 +55,5 @@ Exposed links:
 
 ### Linked entities
 #### metadata
-**/api/confg/submissionupload/:upload-name/metadata**
+**/api/config/submissionuploads/:upload-name/metadata**
 The [submission-form](submissionforms.md) used for the metadata of the files
diff --git a/subscriptions.md b/subscriptions.md
@@ -61,7 +61,7 @@ Return codes:
 * 403 Forbidden - if you are not logged in with sufficient permissions. Only administrators can access the endpoint
 
 ## Single Subscription Object
-**GET /api/core/subscription/<:id>**
+**GET /api/core/subscriptions/<:id>**
 
 Provide detailed information about a specific subscription.
 The JSON response document is as follow
@@ -101,7 +101,7 @@ Status codes:
 
 ### Search methods
 #### findByEPerson
-**GET /api/core/subscription/search/findByEPerson?uuid=<:ePerson-uuid>**
+**GET /api/core/subscriptions/search/findByEPerson?uuid=<:ePerson-uuid>**
 
 The supported parameters are:
 * page, size [see pagination](README.md#Pagination)
@@ -244,7 +244,7 @@ Return codes:
 * 422 Unprocessable Entity - if the subscriptionType or subscriptionParameter name or value are invalid
 
 ## Updating subscription
-** PUT /api/core/subscription/<:id>**
+** PUT /api/core/subscriptions/<:id>**
 
 It is possible to update a subscription with id
 `curl -X PUT '{dspace7-url}/api/core/subscriptions/{id}

diff --git a/versionhistory.md → versionhistories.md b/versionhistory.md → versionhistories.md
@@ -42,7 +42,7 @@ Provide information about for a version history id.
 }
 ```
 Attributes:
-- draftVersion: true, if the most recent version is associated to an item still in progress (workspace or workflow), false otherwise. This attribute is only visible to users allowed to create a new version in the history, see [Create version endpoint](version.md#Create version) 
+- draftVersion: true, if the most recent version is associated to an item still in progress (workspace or workflow), false otherwise. This attribute is only visible to users allowed to create a new version in the history, see [Create version endpoint](versions.md#Create version) 
 
 Status codes:
 * 200 OK - if the version history exists and is accessible by the current user
@@ -57,7 +57,7 @@ Status codes:
 **GET /api/versioning/versionhistories/<:versionHistoryId>/versions**
 
 Retrieve a pageable list of versions for the provided version history identifier.  
-The versions are ordered by version number descending and attributes are secured as described in the [get single version endpoint](version.md#get-single-version).
+The versions are ordered by version number descending and attributes are secured as described in the [get single version endpoint](versions.md#get-single-version).
 Only versions related to archived or withdrawn items are return, the most recent version will be excluded from this list if it is not yet archived.
 
 ```json

diff --git a/version.md → versions.md b/version.md → versions.md
@@ -115,7 +115,7 @@ Return codes:
 
 ### Version History
 
-Retrieves the related version history, for details see [Version history](versionhistory.md)
+Retrieves the related version history, for details see [Version history](versionhistories.md)
 
 ### Item
 

diff --git a/workspaceitem-data-upload.md b/workspaceitem-data-upload.md
@@ -5,43 +5,47 @@ The section data represent the data about the user uploaded files
 
 ```json
 {
-	"files": [ 
-  	 	{
-  	 		metadata: {
-  	 			"dc.title" : [{value: "sample_file.pdf"}],
-  	 			"dc.description" : [{value: "Description of the sample file"}]
-  	 		},
-  	 		"sizeBytes": 8528,
-			"checkSum": {
-			    "checkSumAlgorithm": "MD5",
-			    "value": "9d8f0f9e369cf12159d47c146c499cf4"
-			},
-  	 		"url": "https://demo.dspace.org/server/api/core/bitstreams/00001abf-b2e0-477a-99de-104db7cb6469/content",
-  	 		"accessConditions": [
-  	 			{
-  	 				"id": 123,
-	  	 			"name": "openaccess"
-  	 			},
-  	 			{
-  	 				"id": 126,
-	  	 			"name": "administrator"
-  	 			},
-  	 			{
-  	 				"id": 127,
-	  	 			"name": "embargo",
-	  	 			"startDate": "2018-06-24T00:40:54.970+0000"
-  	 			},
-  	 			{
-  	 				"id": 128,
-	  	 			"name": "lease",
-	  	 			"endDate": "2017-12-24T00:40:54.970+0000"
-  	 			}
-  	 		]
- 		}
- 	]
+    "primary": "00001abf-b2e0-477a-99de-104db7cb6469",
+    "files": [ 
+           {
+            "uuid": "00001abf-b2e0-477a-99de-104db7cb6469",
+            "metadata": {
+              "dc.title" : [{value: "sample_file.pdf"}],
+              "dc.description" : [{value: "Description of the sample file"}]
+           },
+           "sizeBytes": 8528,
+           "checkSum": {
+               "checkSumAlgorithm": "MD5",
+               "value": "9d8f0f9e369cf12159d47c146c499cf4"
+           },
+           "url": "https://demo.dspace.org/server/api/core/bitstreams/00001abf-b2e0-477a-99de-104db7cb6469/content",
+           "accessConditions": [
+              {
+                  "id": 123,
+                  "name": "openaccess"
+              },
+              {
+                  "id": 126,
+                  "name": "administrator"
+              },
+              {
+                  "id": 127,
+                  "name": "embargo",
+                  "startDate": "2018-06-24T00:40:54.970+0000"
+              },
+              {
+                  "id": 128,
+                  "name": "lease",
+                  "endDate": "2017-12-24T00:40:54.970+0000"
+              }
+           ]
+        }
+    ]
 }
 ```
-the files attribute contains the list of user uploaded file in the section. For each file the following attributes exist
+the primary attribute contains eventually the uuid of the bitstream set as primary, it will be null if no primary bitstream is set for the ORIGINAL bundle.
+The files attribute contains the list of user uploaded file in the section. For each file the following attributes exist
+* id: the uuid of the underlying bitstream. Useful to set the primary attribute
 * metadata: the map of the metadata assigned to the specific file with [the same structure](workspaceitem-data-metadata.md) used in the submission-form sectionType for the item metadata
 * sizeBytes (**READ-ONLY**): the size of the received file as calculated on the server at the receiving time 
 * checkSum (**READ-ONLY**): the checksum details (algorithm and value) of the received file as calculated on the server at the receiving time
@@ -54,7 +58,7 @@ The PATCH method expects a JSON body according to the [JSON Patch specification
 Each successful Patch operation will return a HTTP 200 CODE with the new workspaceitem as body. See also the [General rules for the Patch operation](patch.md) for more details.
 
 ### Add
-The add operation is used to add new metadata or access condition to already uploaded files. To upload a completely new file a [POST Multipart request must be issued against the workspaceitems endpoint, see here](workspaceitems.md).
+The add operation is used to add new metadata, access condition to already uploaded files or to set the primary bitstream for the ORIGINAL bundle. To upload a completely new file a [POST Multipart request must be issued against the workspaceitems endpoint, see here](workspaceitems.md).
 
 #### Metadata
 To add a value to an **existent metadata** the client must send a JSON Patch ADD operation as follow
@@ -73,57 +77,60 @@ for instance the call
 `curl --data '{[ { "op": "add", "path": "/sections/uploads/files/0/metadata/dc.title", "value": [{value: "MyFile.pdf"}]}]}' -X PATCH ${dspace7-url}/api/submission/workspaceitems/1`
 
 will set the title of the first uploaded file to MyFile.pdf returning the following json document
+
 ```json
 {
-	id: 1,
-	type: "workspaceitem",
-	sections:
-	{
-		"traditional-page1":
-		{
-		  "dc.title" : [{value: "Sample Submission Item", language: "en"}],
-		  "dc.contributor.author" : [
-		  	 		{value: "Bollini, Andrea", authority: "rp00001", confidence: 600}
-		  ]
-		},
-		"uploads":
-		{	
-			"files": [ 
-	  	 	{
-	  	 		metadata: {
-	  	 			"dc.title" : [{value: "MyFile.pdf"}],
-	  	 			"dc.description" : [{value: "Description of the sample file"}]
-	  	 		},
-	  	 		"sizeBytes": 8528,
-				"checkSum": {
-				    "checkSumAlgorithm": "MD5",
-				    "value": "9d8f0f9e369cf12159d47c146c499cf4"
-				},
-	  	 		"url": "https://demo.dspace.org/server/api/core/bitstreams/00001abf-b2e0-477a-99de-104db7cb6469/content",
-	  	 		"accessConditions": [
-	  	 			{
-	  	 				"id": 123,
-		  	 			"name": "openaccess"
-	  	 			},
-	  	 			{
-	  	 				"id": 126,
-		  	 			"name": "administrator"
-	  	 			},
-	  	 			{
-	  	 				"id": 127,
-		  	 			"name": "embargo",
-		  	 			"startDate": "2018-06-24T00:40:54.970+0000"
-	  	 			},
-	  	 			{
-	  	 				"id": 128,
-		  	 			"name": "lease",
-		  	 			"endDate": "2017-12-24T00:40:54.970+0000"
-	  	 			}
-	  	 		]
-	 		}
- 		]
-		}
-	}
+    "id": 1,
+    "type": "workspaceitem",
+    "sections":
+    {
+       "traditional-page1":
+       {
+         "dc.title" : [{value: "Sample Submission Item", language: "en"}],
+         "dc.contributor.author" : [
+                {alue: "Bollini, Andrea", authority: "rp00001", confidence: 600}
+         ]
+       },
+       "uploads":
+       {
+           "primary": null,
+           "files": [
+           {
+                "uuid": "00001abf-b2e0-477a-99de-104db7cb6469",
+                "metadata": {
+                  "dc.title" : [{value: "MyFile.pdf"}],
+                  "dc.description" : [{value: "Description of the sample file"}]
+              },
+              "sizeBytes": 8528,
+              "checkSum": {
+                  "checkSumAlgorithm": "MD5",
+                  "value": "9d8f0f9e369cf12159d47c146c499cf4"
+              },
+              "url": "https://demo.dspace.org/server/api/core/bitstreams/00001abf-b2e0-477a-99de-104db7cb6469/content",
+              "accessConditions": [
+                  {
+                     "id": 123,
+                     "name": "openaccess"
+                  },
+                  {
+                     "id": 126,
+                     "name": "administrator"
+                  },
+                  {
+                     "id": 127,
+                     "name": "embargo",
+                     "startDate": "2018-06-24T00:40:54.970+0000"
+                  },
+                  {
+                     "id": 128,
+                     "name": "lease",
+                     "endDate": "2017-12-24T00:40:54.970+0000"
+                  }
+              ]
+           }
+           ]
+       }
+    }
 }
 ```
 
@@ -150,6 +157,13 @@ will be rejected because a startDate attribute is also expected when an embargo
 
 Please note that doesn't make sense to add an access condition in a specific index and, to simplify the client implementation it was assumed that the accessCondition array is never *null* but eventually an empty array so that you call always append new AccessCondition to the path "/sections/<:name-of-the-form>/files/<:file-idx>/accessCondition/-".
 
+#### Primary bitstream
+To set a bitstream as primary bitstream of the ORIGINAL bundle you can use a JSON Patch ADD operation as follow
+
+`curl --data '{[ { "op": "add", "path": "/sections/<:name-of-the-form>/primary", "value": "<uuid-of-the-bitstream>"}]}' -X PATCH ${dspace7-url}/api/submission/workspaceitems/<:id>`
+
+The specified uuid must match the uuid of an existing bitstreams in the ORIGINAL bundle of the item related to the inprogress submission. If the uuid is invalid or incorrect the 422 response code will be returned. Please note that the add operation can be used to either set the primary bitstream for the first time or to update it
+
 ### Remove
 It is possible to remove an uploaded file specifying its index in the path of a remove operation 
 `curl --data '{[ { "op": "remove", "path": "/sections/uploads/files/<:idx-file>"}]' -X PATCH ${dspace7-url}/api/submission/workspaceitems/1`
@@ -164,6 +178,11 @@ To remove a previous applied access condition it is sufficient to invoke a remov
 the following request will reset the access condition of the specified file to the empty array
 `curl --data '{[ { "op": "remove", "path": "/sections/uploads/files/<:idx-file>/accessConditions"}]' -X PATCH ${dspace7-url}/api/submission/workspaceitems/1`
 
+#### Primary bitstream
+To unset the primary bitstream of the ORIGINAL bundle you can use a JSON Patch REMOVE operation as follow
+
+`curl --data '{[ { "op": "remove", "path": "/sections/<:name-of-the-form>/primary"}]}' -X PATCH ${dspace7-url}/api/submission/workspaceitems/<:id>`
+
 ### Replace
 The replace operation allows to replace *existent* information with new one. Attempt to use the replace operation without a previous value must return an error. See [general errors on PATCH requests](patch.md)
 
@@ -184,6 +203,13 @@ to transform an existent *openaccess* access condition to an *administrator* acc
 
 please note that the above works only because of openaccess and administrator have the same settings needs (no need of addition information). Indeed, the backend is expected to remove the existent policy and create a new policy. If the settings of the previous and new access condition differs the request must fail with a 422 error code
 
+#### Primary bitstream
+To replace the bitstream set as primary bitstream of the ORIGINAL bundle you can use a JSON Patch REPLACE operation as follow
+
+`curl --data '{[ { "op": "replace", "path": "/sections/<:name-of-the-form>/primary", "value": "<uuid-of-the-bitstream>"}]}' -X PATCH ${dspace7-url}/api/submission/workspaceitems/<:id>`
+
+The specified uuid must match the uuid of an existing bitstreams in the ORIGINAL bundle of the item related to the inprogress submission. Please note that the replace operation can be only used if a previous bitstream was set as primary, if you are uncertain about the current status or you need to set the primary bitstream for the first time use the "add" operation. If the uuid is invalid, incorrect or no primary bitstream was previously set the 422 response code will be returned. 
+
 ### Move
 The move operation is allowed to the files index path to change the order of the uploaded file.