Overview of DELETEs

Within the context of APIs that are fully REST-compliant, 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 Cloud API method 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 method 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, start a new request by clicking the + to the right of the Launchpad tab.
    1. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
  2. The sample data includes one "Review risk information" activity for Alice Applegate. Query for that activity by entering the following call and clicking Send:
    1. GET http://localhost:8180/pc/rest/common/v1/activities?filter=subject:sw:Review%20risk
  3. Identify the id of the activity in the payload. This value is referenced below as <activityId>.
  4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab tab.
    1. On the Authorization tab, select Basic Auth using user aclinton and password gw.
  5. Change the operation to POST and enter the following URL, but do not click Send yet:
    1. POST http://localhost:8180/pc/rest/common/v1/activities/<activityId>/notes
  6. 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"
      }
    }
}
  7. Click Send. In the response payload, identify the note's id.
  8. Open a third request tab and right-clicking the second tab and selecting Duplicate Tab tab.
    1. Because it is a duplicate of the second tab, this tab also uses user aclinton.
  9. Change the operation to DELETE, enter the following URL, but do not click Send yet:
    1. DELETE http://localhost:8180/pc/rest/common/v1/notes/<noteID>
  10. DELETEs cannot specifies request bodies. On the third tab, navigate to the Body tab and select the none radio button.
  11. Click Send. (The response to a successful DELETE is "204 - No content".)

Checking your work

Resend the request on the third tab. This request returns a "No resource was found" error because it is attempting to DELETE a note that has already been DELETEd.