IPA-108: Delete

In REST APIs, it is customary to make a DELETE request to a resource's URI (for example, /groups/{groupId}/clusters/{clusterName}) to delete that resource.

State

Adopt

Guidance

• APIs should provide a Delete method for resources unless it is not valuable for users to do so
• The HTTP verb must be DELETE
• The response should be empty
  • Empty response must return 204 No Content status
• The request must not include a body
• The Delete method should succeed if and only if a resource was present and was successfully deleted
  • If the resource did not exist, the method should respond with a NOT FOUND error

Example

DELETE /groups/${groupId}/clusters/${clusterName}

Cascading Delete

Sometimes, it may be necessary for users to be able to delete a resource as well as all applicable child resources. However, since deletion is usually permanent, it is also important that users not do so accidentally, as reconstructing wiped-out child resources may be quite challenging.

If an API allows deletion of a resource that may have child resources, the API should provide a cascading=true query parameter.

Example

DELETE /groups/{groupId}/clusters/{clusterName}?cascading=true

Error Handling

See IPA-114: Errors for guidance on error handling and documentation.

Naming

• Operation ID must be unique
• Operation ID must be in camelCase
• Operation ID must start with the verb “delete”
• Operation ID should be followed by a noun or compound noun
• The noun(s) in the Operation ID should be the collection identifiers from the resource identifier in singular form

Examples:

Resource Identifier	Operation ID
/groups/${groupId}/clusters/${clusterName}	deleteGroupCluster