Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Episodes endpoint #95

Draft
wants to merge 5 commits into
base: main
Choose a base branch
from
Draft

Episodes endpoint #95

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3a2d2ed
Initial draft episodes overview
keunes Jun 27, 2024
3ef2756
Add Core & Optional badges
keunes Jun 28, 2024
e99fded
Avoid wrapping field names in tables
keunes Nov 2, 2024
e0b3ad1
Update Episodes enpoint spec
keunes Nov 2, 2024
2f74ab1
Add episodes endpoint schema
keunes Nov 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 21 additions & 1 deletion astro.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ export default defineConfig({
starlight({
title: "Open Podcast API",
favicon: "favicon.ico",
customCss: [
'./src/styles/custom.css',
],
social: {
github: "https://github.com/OpenPodcastApi/api-specs",
},
Expand Down Expand Up @@ -43,11 +46,26 @@ export default defineConfig({
},
{
label: "Subscriptions",
badge: {
text: "Core",
variant: "caution",
},
collapsed: true,
autogenerate: {
directory: "specs/subscriptions",
},
},
{
label: "Episodes",
badge: {
text: "Core",
variant: "caution",
},
collapsed: true,
autogenerate: {
directory: "specs/episodes",
},
},
],
},
...openAPISidebarGroups,
Expand All @@ -64,7 +82,9 @@ export default defineConfig({
"TabItem",
],
},
"src/components/SponsorCallout.astro"
"src/components/SponsorCallout.astro",
"src/components/BadgeOptional.astro",
"src/components/BadgeCore.astro"
],
}),
],
Expand Down
212 changes: 210 additions & 2 deletions schema.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ info:
tags:
- name: Subscriptions
description: All actions relating to subscription management
- name: Episodes
description: All actions relating to episode management
paths:
/subscriptions:
get:
Expand Down Expand Up @@ -202,6 +204,51 @@ paths:
security:
- podcast_auth:
- read:subscriptions
/episodes:
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Sporiff Could I ask you to review? I tried to follow the format of the existing file :-)

get:
tags:
- Episodes
summary: Retrieve all episodes for the authenticated user
description: Retrieve all episodes that has changed for the authenticated user since the provided timestamp
operationId: getEpisodes
parameters:
- in: query
name: since
schema:
type: string
format: date-time
required: false
example:
'2022-04-23T18:25:43.511Z'
- in: query
name: page
schema:
type: number
required: false
example:
1
- in: query
name: per_page
schema:
type: number
required: false
example:
5
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Episodes'
application/xml:
schema:
$ref: '#/components/schemas/Episodes'
'401':
$ref: '#/components/responses/Unauthorized'
security:
- podcast_auth:
- read:subscriptions
components:
responses:
Unauthorized:
Expand Down Expand Up @@ -550,6 +597,167 @@ components:
subscription_changed: 2023-02-23T14:41:00.000Z
guid_changed: 2023-02-23T14:41:00.000Z
new_guid: 965fcecf-ce04-482b-b57c-3119b866cc61
Episode:
xml:
name: episode
required:
- podcast_guid
- sync_id
- episode_guid
- title
- publish_date
- enclosure_url
- episode_url
type: object
properties:
podcast_guid:
type: string
format: guid
sync_id:
type: string
format: guid
episode_guid:
type: string
title:
type: string
publish_date:
type: string
format: date-time
enclosure_url:
type: string
format: url
episode_url:
type: string
format: url
playback_position:
value:
type: number
format: integer
timestamp:
type: string
format: date-time
played_status:
value:
type: boolean
timestamp:
type: string
format: date-time
new_status:
value:
type: boolean
timestamp:
type: string
format: date-time
download_status:
value:
type: boolean
timestamp:
type: string
format: date-time
favorite_status:
value:
type: boolean
timestamp:
type: string
format: date-time
example:
podcast_guid: 31740ac6-e39d-49cd-9179-634bcecf4143
sync_id: cff3ea32-4215-4f98-bc23-5358d1f35b55
episode_guid: https://example.com/podcast/episode-5-the-history-of-RSS
title: The history of RSS
publish_date: 2022-04-24T17:53:21.573Z
enclosure_url: https://example.com/podcast/episode-5-the-history-of-RSS.mp3
episode_url: https://example.com/podcast/episode-5-the-history-of-RSS
playback_position:
value: 0
timestamp: 2024-11-02T13:19
played_status:
value: true
timestamp: 2024-11-02T13:19
new_status:
value: false
timestamp: 2024-10-30T17:31
download_status:
value: false
timestamp: 2024-11-02T13:19
favorite_status:
value: false
timestamp: 2024-11-02T13:19
Episodes:
required:
- total
- page
- per_page
- episodes
xml:
name: episodes
type: object
properties:
total:
type: number
page:
type: number
per_page:
type: number
next:
type: string
format: url
previous:
type: string
format: url
episodes:
type: array
items:
$ref: '#/components/schemas/Episode'
example:
total: 2
page: 1
per_page: 5
episodes:
- podcast_guid: 31740ac6-e39d-49cd-9179-634bcecf4143
sync_id: cff3ea32-4215-4f98-bc23-5358d1f35b55
episode_guid: https://example.com/podcast/episode-5-the-history-of-RSS
title: The history of RSS
publish_date: 2022-04-24T17:53:21.573Z
enclosure_url: https://example.com/podcast/episode-5-the-history-of-RSS.mp3
episode_url: https://example.com/podcast/episode-5-the-history-of-RSS
playback_position:
value: 0
timestamp: 2024-11-02T13:19
played_status:
value: true
timestamp: 2024-11-02T13:19
new_status:
value: false
timestamp: 2024-10-30T17:31
download_status:
value: false
timestamp: 2024-11-02T13:19
favorite_status:
value: false
timestamp: 2024-11-02T13:19
- podcast_guid: 9d6786c9-ed48-470d-acbe-e593547f4b5b
sync_id: 5773f457-e71b-417d-8ea8-f07c38a03a3e
episode_guid: 01999e25-08cd-4f29-a61e-6ca459b40d27
title: Walk with the weatherman
publish_date: 2022-04-27T19:35:20.000Z
enclosure_url: https://op3.dev/e/https://podcasts.example2.net/audio/@digitalcitizen/49-walk-with-the-weatherman.mp3
episode_url: https://podcasts.example2.net/@digitalcitizen/episodes/49-walk-with-the-weatherman
playback_position:
value: 2100
timestamp: 2024-11-01T17:38
played_status:
value: false
timestamp: 2024-04-28T09:20
new_status:
value: false
timestamp: 2024-11-01T17:02
download_status:
value: true
timestamp: 2024-11-01T17:02
favorite_status:
value: false
timestamp: 2024-04-28T09:20
Deletion:
xml:
name: deletion
Expand Down Expand Up @@ -599,8 +807,8 @@ components:
implicit:
authorizationUrl: https://test.openpodcastapi.com/oauth/authorize
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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think reading & writing subscriptions & episodes can both be in the same scope. Would you agree @Sporiff @JonOfUs?

read:subscriptions: read your subscription information & related episodes
api_key:
type: apiKey
name: api_key
Expand Down
5 changes: 5 additions & 0 deletions src/components/BadgeCore.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
import { Badge } from '@astrojs/starlight/components';
---

<Badge text="Core" variant="caution" size="small" />
5 changes: 5 additions & 0 deletions src/components/BadgeOptional.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
import { Badge } from '@astrojs/starlight/components';
---

<Badge text="Optional" variant="success" size="small" />
Loading