[ADP-114] DELETE

Overview

The HTTP DELETE method is used to delete a specified resource. When a DELETE request is received, the server should delete the resource identified by the URI and return a response indicating the outcome of the operation.

Guidance

• The DELETE method MUST be idempotent. Multiple identical DELETE requests MUST have the same effect as a single request.

• When appropriate, MAY implement soft delete instead of hard delete. This allows for data recovery and maintains referential integrity.

  • Please refer to Soft Deletion.

• DELETE operations MUST require proper authentication to prevent unauthorized deletions.

• Implement proper access control to ensure users can only delete resources they have permission for.

• Responses

  • Upon successful deletion, the server SHOULD return a 204 No Content status code.
  • DRAFT If you are implementing soft deletion, you MAY return the resource being deleted or the deleted resource in the response body.
  • For asynchronous deletions, MAY return a 202 Accepted status code.
  • If the resource does not exist, SHOULD return a 404 Not Found status code with a Problem Details object.
  • If the user is authenticated but not authorized to delete the resource, SHOULD return a 403 Forbidden status code with a Problem Details object.

• Support conditional DELETE requests using headers such as If-Match or If-Unmodified-Since.

• All error responses MUST use the Problem Details format as defined in RFC 9457.

• As specified in RFC 9110, DELETE requests SHOULD NOT include a request body.

• If the resource to be deleted has associated child resources, the scope of this deletion SHOULD be explicitly stated in the document, whether it includes associated resources. To enhance user experience, it MAY be necessary to provide an option for users to decide whether to delete associated resources. The default value of this option should be "No" to avoid unnecessary resource deletion.

Example

• Successful Deletion

  DELETE /v1/resources/123 HTTP/1.1
  Host: example.com
  Authorization: Bearer <token>
  
  HTTP/1.1 204 No Content

• Non-existent Resource

  DELETE /v1/resources/999 HTTP/1.1
  Host: example.com
  Authorization: Bearer <token>
  
  HTTP/1.1 404 Not Found
  Content-Type: application/problem+json
  
  {
    "type": "https://example.com/problems/not-found",
    "title": "Resource Not Found",
    "status": 404,
    "detail": "The requested resource with ID 999 does not exist.",
    "instance": "/v1/resources/999"
  }

• Unauthorized Request

  DELETE /v1/resources/123 HTTP/1.1
  Host: example.com
  
  HTTP/1.1 401 Unauthorized
  Content-Type: application/problem+json
  
  {
    "type": "https://example.com/problems/unauthorized",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Authentication is required to delete this resource.",
    "instance": "/v1/resources/123"
  }

• Forbidden Request

  DELETE /v1/resources/123 HTTP/1.1
  Host: example.com
  Authorization: Bearer <token>
  
  HTTP/1.1 403 Forbidden
  Content-Type: application/problem+json
  
  {
    "type": "https://example.com/problems/forbidden",
    "title": "Forbidden",
    "status": 403,
    "detail": "You do not have permission to delete this resource.",
    "instance": "/v1/resources/123"
  }

• Conditional Deletion

  DELETE /v1/resources/123 HTTP/1.1
  Host: example.com
  Authorization: Bearer <token>
  If-Match: "etag123"
  
  HTTP/1.1 204 No Content

• Accepted for Processing

  DELETE /v1/resources/123 HTTP/1.1
  Host: example.com
  Authorization: Bearer <token>
  
  HTTP/1.1 202 Accepted

Reference

• RFC 9110: DELETE
• MDN Web Docs: HTTP DELETE
• AIP-135
• Soft Deletion
• Delete Related Resource Discussion

Changelog

• 2024.09.24 Remove unwanted /api path in the samples