Delete a subscription

Core action

This is a core action. All server implementations MUST support it.

Endpoint

DELETE /v1/subscriptions/{guid}

This endpoint allows clients to mark a feed as deleted. This prevents the server from updating the feed in the background and prevents the server from returning any information, such as playback positions, related to the given associated feed.

Server-side behavior

Important

The server MUST enact all cascade deletions using ACID transactions. If the deletion process fails at any point in the transaction, all transactions MUST be rolled back to maintain integrity.

To ensure that DELETE requests are handled asynchronously, the server MUST respond to deletion requests immediately with a 202 (Accepted) status containing a deletion_id. This ID MUST correspond to a status object on the server containing details of the deletion process. The client MUST be able to query the status of a deletion to check its progress.

Parameter	Type	Required?	Description
id	Integer	Yes	The ID of the deletion object
success	Boolean	Yes	Whether or not the deletion was completed successfully
complete	Boolean	Yes	Whether or not the deletion process has finished
message	String	No	A status message indicating the current status of the deletion, or any errors that were encountered

The following flow MUST be followed:

1. The client sends a DELETE request for a subscription object
2. The server creates a new deletion status object and returns the deletion_id in a 202 (Accepted) response
3. The server attempts to perform a cascade delete on all related items
   1. If a failure occurs at any point in the process, all transactions are rolled back and the status object is updated to show the following:
      • complete: Must be true
      • success: Must be false
      • message: Should be updated to contain a meaningful error message
   2. If all deletions are successful, the status object is updated to show the following:
      • complete: Must be true
      • success: Must be true
      • message: Should be updated to contain a success message

If the client attempts to fetch a deleted subscription, the server MUST respond with a 410 (Gone) status code to indicate the object and its associated data have been deleted.

Example request

$ curl --location --request DELETE \
'/v1/subscriptions/2d8bb39b-8d34-48d4-b223-a0d01eb27d71'

Example 202 response

JSON

{
"deletion_id": 25,
"message": "Deletion request was received and will be processed"
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<Success>
   <deletion_id>25</deletion_id>
   <message>Deletion request was received and will be processed</message>
</Success>