2024 06 19

2024-06-19 15:00 (3pm)

Episode endpoint

Data fields

GET episode information

• REQUEST
  • since - ISO8601
  • page (TO UPDATE)
  • per-page (TO UPDATE)
• RESPONSE
  • Identifier fields Which identifiers to send? Always all, or only main ones? If client B is not aware yet of an episode identified by client A, then how does the server know it needs to send all identifiers rather than basic ones only to client B? It can't, would require a 'conversation'. Only a few bytes => we'll always send everything, maybe include parameters for selecting fields later.
    • Podcast GUID
    • Episode sync-id
    • Episode GUID (from RSS)
    • Title
    • Publish date
    • Enclosure URL
    • Episode URL Do we need timestamp here still? No. RSS = source of truth so clients should check that for changes. Not needed to know when changes happen to prevent data loss.
    • Duration - maybe keep for unlikely edge cases, but probably not useful (not all RSS feeds include this, and values likely to differ between RSS feed and actual media file)
  • Data fields One timestamp per field to keep track of changes. NOTE: if statuses are mutually exclusive, then we trust whoever applies a status change to update other statuses accordingly. E.g. if user manually downloads an episode, both Download status and New status MUST be updated.
    • Playback position - in seconds
    • EpisodePlayed status - boolean
    • New status - boolean, indicates that no (user?) interactions took place with a given episode, Inbox in AntennaPod
    • Download status - boolean, make opt-in data, expect client to respect download status if enabled. Delayed download (e.g. wait for WiFi) is permitted. (discussion details)
    • Favorite status - boolean
    • Potential future fields:
      • Bookmark - request in AntennaPod for bookmark with timestamp & notes
      • Tags - request in Kasts for tags for episodes

Options for formatting status fields (affecting both GET and PUT requests, latter in case you sync after your holiday in the desert):

{
    'playback_position': {
        'value': 15,
        'timestamp': 2024-06-19T15:46
    }
}

{
    'playback_position': 15,
    'playback_position.changed': 2024-06-19T15:46
}

Important: this MUST/SHOULD (?) be the timestamp of the actual data change, not the timestamp of sending by client or processing by the server. Reason: when client is offline for a long time, then these changes should not overwrite more changes in other clients which are done more recently but synchronised after. :::info This is not needed if client always first pulls before push. Assuming that the client stores the timestamps of these changes locally. Maybe we should note this as a requirement, rather than submitting the timestamps. Kasts keeps log of changes and wipes on each sync, also keeping track of timestamp of latest sync. :::

Create or edit information of multiple episodes

POST /v1/episodes

• REQUEST - always as array
  • if sync ID known:
    • Podcast GUID
    • Episode sync-ID
    • changed data fields
  • if no sync ID:
    • all identifier fields (except sync-id)
    • temporary ID [optional] arbitrary value that is returned by the server to make re-identification of episode easier, e.g. client's database key
    • changed data fields
• RESPONSE
  • Batch update
    • success array
    • failure array
  • Fields for each episode in array:
    • Podcast GUID
    • Episode sync-ID
    • all data fields + their timestamps where the server has newer information than the client (only relevant to failure array)
    • message - reason for failure (only relevant to failure array)
  • Fields for newly created episodes:
    • all identifier fields - so that clients can map local episodes to sync-ids OR temporary ID if it was submitted
    • all data fields + their timestamps where the server has newer information than the client

Create or edit information of single episodes

PATCH /v1/subscriptions/{guid}/episodes/{sync-id}

• REQUEST
  • changed data fields
• RESPONSE
  • HTTP code says whether action worked
  • all data fields + their timestamps where the server has newer information than the client
  • failure message, if action failed