Episodes endpoint #95
Conversation
✅ Deploy Preview for openpodcastapi ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Explain `download_status` and timestamp field & update table formatting on overview page. Add placeholder page for matching & deduplication. Specify GET /episodes.
keunes
force-pushed
the
episodes-endpoint
branch
from
3a68b75 to
e0b3ad1
Compare
|
|
||
| **Important open discussion point:** | ||
|
|
||
| Sending back & forth timestamps is not needed if client always first pulls before push, and assuming that the client stores the timestamps of these changes locally. Maybe we should note this as a requirement, rather than submitting the timestamps. |
There was a problem hiding this comment.
It's hard to wrap my head around this, but I have the impression that we still need to send the timestamps around. Because the last sync date might be in the past, and you have a more recent change, but the server might have received more recent data from another client in the meantime. @mogwa1?
|
|
||
| ### Episode fields | ||
|
|
||
| | Group | Field | Type | Required? | Description | |
There was a problem hiding this comment.
Having this table seems a bit superfluous actually with the 'important fields' table on the Overview page. Do you think it would be safe to drop it here, and add a reference to the other page, instead @Sporiff?
|
|
||
| This endpoint enables clients to return all episode information relating to the authenticated user. It returns pagination information and an array of `episodes`. | ||
|
|
||
| While supported, this endpoint is expected to be used rarely in practice. More often, episodes are retrieved per queue (TBD) or per subscription (TBD). |
There was a problem hiding this comment.
Did we have an idea yet where/how episodes of a given subscription should be retrieved? /v1/episodes?subscription=x or GET /v1/subscriptions/{guid}/episodes?
Side note: I guess this episode will be used a lot actually, just with the since parameter most of the time.
There was a problem hiding this comment.
Did we have an idea yet where/how episodes of a given subscription should be retrieved? /v1/episodes?subscription=x or GET /v1/subscriptions/{guid}/episodes?
Best practice dictates that you should scope to collections, so GET /v1/subscriptions/{guid}/episodes would be appropriate.
| security: | ||
| - podcast_auth: | ||
| - read:subscriptions | ||
| /episodes: |
There was a problem hiding this comment.
@Sporiff Could I ask you to review? I tried to follow the format of the existing file :-)
| scopes: | ||
| write:subscriptions: modify subscription information for your account | ||
| read:subscriptions: read your subscription information | ||
| write:subscriptions: modify subscription information & related episodes for your account |
There was a problem hiding this comment.
@keunes I think generally it's best practice with Oauth to keep read/write separate. The principle of least privilege dictates that you should give applications/people access only to what they absolutely need to get the job done. If you made an app that could read subscriptions to, for example, display your favorite podcasts on your website, you should not give that app access to modify those subscriptions.
Implements conclusions 2024-06-19