Overview of DELETEs

Within the context of true REST APIs, a DELETE is an endpoint operation that deletes a resource. This typically involves removing the resource from the underlying database.

Within the context of Cloud API, a DELETE is a system API operation that "removes" an existing resource from PolicyCenter. What it means to "remove" the resource depends on the resource type. The DELETE operation federates to the PolicyCenter code that matches the functionality most closely tied to deletion. That code could theoretically:

  • Delete the corresponding data model instance from the operational database.
  • Mark the corresponding data model instance as retired.
  • Modify the corresponding data model instance and other related instances to indicate the data is no longer active or available.

Unlike GET, POST, and PATCH, there are only a small number of endpoints in the base configuration that support DELETE. This is because, in most cases, PolicyCenter does not support the removal of data. Several business objects can be approved, canceled, completed, closed, declined, rejected, retired, skipped, or withdrawn. But only a few can be deleted.

A DELETE call consists of the DELETE operation and the endpoint, such as DELETE /notes/{noteId}. Similar to GETs, DELETEs are not permitted to have a request payload.

The response to a DELETE includes an HTTP code indicating success or failure. DELETE responses do not have a response payload.

Tutorial: DELETE a note

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more information, see Tutorial: Set up your Postman environment.

In this tutorial, you will send calls as Amy Clinton (user name aclinton). In the base configuration, Amy Clinton is an underwriting supervisor who has permission to delete notes. As Amy Clinton, you will create a note and query for it. You will then delete the note and attempt to query for it a second time.

Tutorial steps

  1. In Postman, create an initial request by:
    1. Clicking the + to the right of the Launchpad tab.
    2. Specifying Basic Auth authorization using user aclinton and password gw.
  2. Enter the following call, but do not click Send yet:
    1. POST http://localhost:8180/pc/rest/common/v1/activities/pc:13/notes
  3. Specify the request payload.
    1. In the first row of tabs (the one that starts with Params), click Body.
    2. In the row of radio buttons, select raw.
    3. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
    4. Paste the following into the text field underneath the radio buttons. 
      {
  "data":
    {
      "attributes": {
        "body": "API tutorial note to be deleted"
      }
    }
}
  4. Click Send. In the response payload, identify the note's id.
  5. Create a second request by:
    1. Clicking the + to the right of the Launchpad tab.
    2. Specifying Basic Auth authorization using user aclinton and password gw.
  6. Verify that the new note exists by entering the following call and click Send:
    1. GET http://localhost:8180/pc/rest/common/v1/notes/<noteID>
  7. Create a third request by:
    1. Clicking the + to the right of the Launchpad tab.
    2. Specifying Basic Auth authorization using user aclinton and password gw.
  8. Delete the new note by entering the following call and click Send:
    1. DELETE http://localhost:8180/pc/rest/common/v1/notes/<noteID>
  9. Verify the new note no longer exists by returning to the second tab (the one with the GET) and clicking Send a second time.

Checking your work

The first GET (which was executed before the DELETE) should return details about the note.

The second GET (which was executed after the DELETE) should return an error message similar to the one below:

{
    "status": 404,
    "errorCode": "gw.api.rest.exceptions.NotFoundException",
    "userMessage": "No resource was found at path /common/v1/notes/xc:301"
}