2024 05 28

2024-05-28 12:00 (12pm)

:::info Next meeting: 2024-06-11 12:00 CEST (12:00pm) :::

Episode endpoints assembly

Endpoints

• GET /v1/episodes
• POST /v1/episodes - max. 50 entries per call
• GET /v1/subscriptions/{guid}/episodes
• GET /v1/subscriptions/{guid}/episodes/{sync-id}
• PATCH /v1/subscriptions/{guid}/episodes/{sync-id}

Pagination

Already defined for subscription endpoint.

:::info We need to check if we should change to cursor pagination (for all endpoints). Probably better, as it defines set results, not impacted by GET and POST requests being processed simultaneously (in which case regular pagination changed). :::

Batching; moving PUT under /episodes?

Key use case: moving from one server to another.

Three options:

1. end-point accepts only array, with immediate response

2. submit batch, get back batch ID, checks status for batch ID Batch limit would be good. 50 could be a good limit, still allowing server to reply near-immediate. This is, however, determined by the server implementor. We can implement in API standard approach: POST just for 1, batch (POST with array) for up to 50.

3. all as single transactions Single transactions most REST compliant. But performance unkown. To be checked.

More calls, but web calls are cheap & efficient. Batching on server side still possible. Batching on client side bit more tricky; what if part of the batch fails (e.g. 999 OK, 1 fail). Roll back everything? Status reporting in batch reply? Key question: where is the load issue handled.

Conclusion: We agreed on batch endpoints with a batch limit (option 1). We limit the batch size to 50 by default, this can potentially be handled out with the capabilities. The batch limit ensures that the server can respond in a reasonable time.

:::info We need to update the subscriptions endpoint with this max batch size. ::: :::info We need to update the capabilities endpoint also with this info about non-default values. :::

Deletion

1. Remove (playback) history/stats: PATCH
2. Delete podcast: deletion gets cascaded to episodes on server side
3. Delete episode: not supported

Deduplication (not a high priority)

[...]

/subscriptions/{guid}/episodes

Same as /episodes, but 'filtered' for the subscription collection; returning that sub-set.

Data fields

GET episode information

• REQUEST
  • since - ISO8601
  • page (TO UPDATE)
  • per-page (TO UPDATE)
• RESPONSE
  • Identifier 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 sever 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
    • (Duration?)
  • Status fields One timestamp per field to keep track of changes
    • Playback position
    • Episode status
    • New status
    • Download status?
    • Bookmark/favorite?

POST/PATCH episode information

• REQUEST
• RESPONSE

:::info Next steps:

• Ciaran will do a draft PR
• We'll reconvene Tuesday 11/06 12/12:30 CEST. :::