Delete
In REST APIs, it is customary to make a DELETE
request to a resource’s URI
(for example, /v1/publishers/{publisher}/books/{book}
) in order to delete
that resource.
Resource-oriented design (AEP-121) honors this pattern through the
Delete
method. This method accepts the URI representing that resource and
usually returns an empty response.
Guidance
APIs should generally provide a delete method for resources unless it is not valuable for users to do so.
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
send a 404 Not found
(NOT_FOUND
) error.
If the API is operating on the Management Plane, the method should have
strong consistency: the completion of a delete method must mean that
the existence of the resource has reached a steady-state and reading resource
state returns a consistent 404 Not found
(NOT_FOUND
) response.
Delete methods are specified using the following pattern:
- The method’s name must begin with the word
Delete
. The remainder of the method name should be the singular form of the resource’s name. - The request schema name must exactly match the method name, with a
Request
suffix. - The response message should be an empty object.
- If the delete method is long-running, the response
schema must be an
Operation
which resolves to the correct response.
- If the delete method is long-running, the response
schema must be an
-
The response message should be
google.protobuf.Empty
.- If the delete RPC is long-running, the response
message must be a
aep.api.Operation
which resolves to the correct response.
- If the delete RPC is long-running, the response
message must be a
-
The request message field receiving the resource path should map to the URI path.
- This field should be called
path
. - The
path
field should be the only variable in the URI path. All remaining parameters should map to URI query parameters.
- This field should be called
-
There must not be a
body
key in thegoogle.api.http
annotation. -
There should be exactly one
google.api.method_signature
annotation, with a value of"path"
. If an etag or force field are used, they may be included in the signature.
-
The response body should be omitted.
-
The HTTP response code should be
204 No Content
if the delete was successful.
Requests
Delete methods implement a common request pattern:
- The HTTP verb must be
DELETE
. - There must not be a request body.
- If a delete request contains a body, the body must be ignored, and must not cause an error (this is required by RFC 9110)
- The request must not require any fields in the query string. The request should not include optional fields in the query string unless described in another AEP.
-
A
path
field must be included. It should be calledpath
.- The field should be annotated as required.
- The field must identify the resource type that it references.
-
The comment for the field should document the resource pattern.
-
The request message must not contain any other required fields, and should not contain other optional fields except those described in this or another AEP.
-
Delete methods should return
204 No Content
with no response body, or202 Accepted
with a representation of the operation in the response body if the delete is long-running.
Soft delete
Long-running delete
Some resources take longer to delete than is reasonable for a regular API request. In this situation, the API should use a long-running operation instead: AEP-151.
- The
response
field of the response body must be an empty object to be consistent with the appropriate return type if the method was not long-running.
-
The
response
field of the response must begoogle.protobuf.Empty
to be consistent with the appropriate return type if the method was not long-running. -
Both the
response_type
andmetadata_type
fields must be specified (even if they aregoogle.protobuf.Empty
).
-
The response status code should be
202 Accepted
if the request was accepted for later processing. When the request is processed it could still fail. -
Both the
response_type
andmetadata_type
fields must be specified.
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 difficult.
If an API allows deletion of a resource that may have child resources, the API
must provide a bool force
field on the request, which the user sets to
explicitly opt in to a cascading delete.
The API must fail with a FAILED_PRECONDITION
error if the force
field
is false
(or unset) and child resources are present.
The API must fail with a 409 Conflict
error if the force
field is
false
(or unset) and child resources are present.
Errors
If the user does not have permission to access the resource, regardless of
whether or not it exists, the service must error with 403 Forbidden
(PERMISSION_DENIED
). Permission must be checked prior to checking if the
resource exists.
If the user does have proper permission, but the requested resource does not
exist, the service must error with 404 Not found
(NOT_FOUND
).
Further reading
- For soft delete and undelete, see AEP-164.
- For bulk deleting large numbers of resources based on a filter, see AEP-165.
Changelog
- 2024-02-11: From from https://google.aip.dev/135