Deleting Data Resources

Finally, after presenting several creation and access scenarios, let’s briefly cover the removal of resources. First things first, it is NOT possible to permanently remove resources via the RESTful API. The DELETE operation is implemented in a way of revoking resources to make them invisible to users, but as they might be references internally or externally, they are never removed from the system unless using additional tools. The following request shows how a DELETE operation is performed on an existing resource.

$ curl 'http://localhost:8080/api/v1/dataresources/edbf964c-f215-4fc6-9ef1-2ff1ea5a811e' -i -X DELETE \
    -H 'If-Match: "-2010363665"'

You can see that you need the resource URL as well as the current ETag.

DELETE /api/v1/dataresources/edbf964c-f215-4fc6-9ef1-2ff1ea5a811e HTTP/1.1
If-Match: "-2010363665"
Host: localhost:8080

The server responds with status HTTP NO_CONTENT (204) to all returning delete requests, even if the resource has been deleted already.

HTTP/1.1 204 No Content

As soon as the resource was REVOKED, no user will be able to see or access the resource. A request to the resource URL will result in an HTTP status NOT_FOUND (404). However, revoked resources are still visible to the owner(s) of the resource (person(s) possessing ADMINISTATE permission) or the system administrator (person(s) possessing the ADMINISTRATOR role). They still can access and modify the resource, e.g. in order to change back the state to VOLATILE or FIXED in order to ‘undo’ the deletion.

If no authentication is enabled, which is assumed by this documentation, the deletion of resources only changes the state to REVOKED. The system account used for authentication-less access is automatically the owner of all resources, which grants this account the access even to revoked resources. This is shown in the following example.

$ curl 'http://localhost:8080/api/v1/dataresources/edbf964c-f215-4fc6-9ef1-2ff1ea5a811e' -i -X GET

We are trying a normal HTTP GET to the resource we just deleted. According to the description above, we should receive a positive response showing us a resource with state REVOKED.

GET /api/v1/dataresources/edbf964c-f215-4fc6-9ef1-2ff1ea5a811e HTTP/1.1
Host: localhost:8080

The response looks as expected. The resource we’ve deleted with the changed state.

HTTP/1.1 200 OK
ETag: "-943498966"
Resource-Version: 5
Content-Type: application/json
Content-Length: 1104

{
  "id" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e",
  "identifier" : {
    "id" : 1,
    "value" : "(:tba)",
    "identifierType" : "DOI"
  },
  "creators" : [ {
    "id" : 1,
    "familyName" : "Doe",
    "givenName" : "John",
    "affiliations" : [ "Karlsruhe Institute of Technology" ]
  } ],
  "titles" : [ {
    "id" : 1,
    "value" : "Most basic resource for testing",
    "titleType" : "OTHER"
  } ],
  "publisher" : "KIT Data Manager",
  "publicationYear" : "2017",
  "resourceType" : {
    "id" : 1,
    "value" : "testingSample",
    "typeGeneral" : "DATASET"
  },
  "dates" : [ {
    "id" : 1,
    "value" : "2022-03-25T12:47:06Z",
    "type" : "CREATED"
  } ],
  "alternateIdentifiers" : [ {
    "id" : 1,
    "value" : "edbf964c-f215-4fc6-9ef1-2ff1ea5a811e",
    "identifierType" : "INTERNAL"
  }, {
    "id" : 2,
    "value" : "resource-1-231118",
    "identifierType" : "OTHER"
  } ],
  "lastUpdate" : "2022-03-25T12:47:08.422Z",
  "state" : "REVOKED",
  "acls" : [ {
    "id" : 1,
    "sid" : "SELF",
    "permission" : "ADMINISTRATE"
  } ]
}

That’s the reason why another resource state has been introduced in case a resource should be hidden entirely from all users. This state is called GONE and is assigned if a revoked resource is deleted by an ADMINISTRATOR. Of course, the GONE state can also be assigned via PATCH operation, but deleting a resource twice is the typical approach to do so. Let’s try applying a delete operation a second time.

DELETE /api/v1/dataresources/edbf964c-f215-4fc6-9ef1-2ff1ea5a811e HTTP/1.1
If-Match: "-943498966"
Host: localhost:8080

The response looks as expected delivering status status HTTP NO_CONTENT (204).

HTTP/1.1 204 No Content

However, if we now try to access the resource again via HTTP GET…

GET /api/v1/dataresources/edbf964c-f215-4fc6-9ef1-2ff1ea5a811e HTTP/1.1
Host: localhost:8080

…we’ll receive nothing but the status HTTP NOT_FOUND (404). From now on, the resource is no longer accessible by anybody via RESTful endpoints. The only possibility to re-allow resource access is to modify its state in the database.

---

WARNING

In contrast to deleting entire resource, deleting single content elements is permanent. If you send a DELETE request to a data URL of a resource, the associated file and all metadata associated with the particular element are deleted. This operation is not reversible and you should double check before deleting a content element.

---