Update a subscription

PATCH /v1/subscriptions/{guid}

This endpoint allows clients to update information about a subscription. The client MAY update the following information:

The podcast’s GUID
The podcast’s feed URL
An update to the subscription status for the user

This endpoint returns the following information:

Field	Type	Required?	Description
`new_feed_url`	String	No	The URL of the podcast RSS feed. Only returned if the `feed_url` field was updated by the request
`is_subscribed`	Boolean	No	Whether the user is subscribed to the podcast or not. Only returned if the `is_subscribed` field was updated by the request
`subscription_changed`	Datetime	No	The date on which the `is_subscribed`or `feed_url` field was last updated. Presented in ISO 8601 format. Only returned if the `is_subscribed` field was updated by the request
`guid_changed`	Datetime	No	The date on which the podcast’s GUID was last updated. Presented in ISO 8601 format. Only returned if the `guid` field was updated by the request
`new_guid`	String<UUID>	No	The new GUID associated with the podcast. Only returned if the `guid` field was updated by the request

Parameters

The client MUST pass the subscription GUID in the query path and add at least one field update in the request body.

Parameter	Type	In	Required?	Description
`guid`	String	Query	Yes	The GUID of the subscription object that needs to be updated
`new_feed_url`	String	Body	No	The URL of the new RSS feed for the subscription
`new_guid`	String <UUID>	Body	No	The new GUID of the podcast
`is_subscribed`	Boolean	Body	No	Whether the user is subscribed to the podcast or not

Server-side behavior

On receipt of a PATCH request for a subscription, the server MUST do the following:

If the subscription in the request has a new_guid specified in the database, follow the new_guid chain to find the latest version of the subscription
If the request contains a new_feed_url parameter:
1. Update the subscription entry’s feed_url field to the new value
2. Update the subscription entry’s subscription_changed field to the current date
If the request contains a new_guid parameter:
1. Check if the GUID is already present in the system
2. If the GUID is already present, update the subscription entry’s new_guid field to point to the existing entry
3. If the GUID isn’t already present, create a new subscription entry and update the existing entry’s new_guid field to point to the newly created entry
4. Update the subscription entry’s guid_changed to the current date
If the request contains an is_subscribed parameter:
1. Update the subscription entry’s is_subscribed to the new value
2. Update the subscription entry’s subscription_changed field to the current date
Return a summary of the changes

A flowchart of the subscription update process

$ curl --location --request PATCH '/subscriptions/2d8bb39b-8d34-48d4-b223-a0d01eb27d71' \
--header 'Content-Type: application/json' \
--data '{
   "new_feed_url": "https://example.com/rss5",
   "new_guid": "965fcecf-ce04-482b-b57c-3119b866cc61",
   "is_subscribed": false
}'

$ curl --location --request PATCH '/subscriptions/2d8bb39b-8d34-48d4-b223-a0d01eb27d71' \
--header 'Content-Type: application/xml' \
--data '<?xml version="1.0" encoding="UTF-8"?>
<subscription>
   <new_feed_url>https://example.com/rss5</new_feed_url>
   <new_guid>965fcecf-ce04-482b-b57c-3119b866cc61</new_guid>
   <is_subscribed>false</is_subscribed>
</subscription>'

Example 200 response

JSON
XML

{
   "new_feed_url": "https://example.com/rss5",
   "is_subscribed": false,
   "subscription_changed": "2023-02-23T14:41:00.000Z",
   "guid_changed": "2023-02-23T14:41:00.000Z",
   "new_guid": "965fcecf-ce04-482b-b57c-3119b866cc61"
}

<?xml version="1.0" encoding="UTF-8"?>
<subscription>
   <new_feed_url>https://example.com/rss5</new_feed_url>
   <is_subscribed>false</is_subscribed>
   <subscription_changed>2023-02-23T14:41:00.000Z</subscription_changed>
   <guid_changed>2023-02-23T14:41:00.000Z</guid_changed>
   <new_guid>965fcecf-ce04-482b-b57c-3119b866cc61</new_guid>
</subscription>