Get a single subscription

Core action

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

Endpoint

GET /v1/subscriptions/{guid}

This endpoint returns subscription information relating to a specific subscription for the authenticated user. It returns the following information:

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

Parameters

The client MUST send the subscription’s guid in the path of the request.

Server-side behavior

If the entry contains a new_guid, the server MUST return the newest guid associated with the entry in the response’s new_guid field. For example: if a subscription has received 2 new guids, the server MUST return:

• The subscription’s guid passed in the request path
• The subscription’s latest guid in the new_guid field

This ensures the client has the most up-to-date entry for the subscription.

Client behavior

The client SHOULD update its local subscription data to match the information returned in the response. On receipt of a deleted subscription, the client SHOULD present the user with the option to remove their local data or send their local data to the server to reinstate the subscription details.

Example request

JSON

$ curl -X 'GET' \
'/v1/subscriptions/968cb508-803c-493c-8ff2-9e397dadb83c' \
-H 'accept: application/json'

XML

$ curl -X 'GET' \
'/v1/subscriptions/968cb508-803c-493c-8ff2-9e397dadb83c' \
-H 'accept: application/xml'

Example 200 response

JSON

{
   "feed_url": "https://example.com/feed2",
   "guid": "968cb508-803c-493c-8ff2-9e397dadb83c",
   "is_subscribed": true
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<subscription>
   <feed_url>https://example.com/feed2</feed_url>
   <guid>968cb508-803c-493c-8ff2-9e397dadb83c</guid>
   <is_subscribed>true</is_subscribed>
</subscription>

Example 410 response

If a subscription has been deleted, the server must respond with a 410 (Gone) response to inform the client.

JSON

{
   "code": 410,
   "message": "Subscription has been deleted"
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<Error>
   <code>410</code>
   <message>Subscription has been deleted</message>
</Error>