Add new podcast by API

[geraldo]

I would like to add new podcasts and episodes by the API but don't find any information about the first.

We are a community radio network and offer all the radio content as podcasts. Now we are looking for a open/libre podcast directory to submit our content and we are actually evaluation fyyd and gpodder.

[stefankoegl]

A podcast is automatically added once the first user subscribes to it. Then gpodder.net should automatically and periodically fetch the latest episodes. A dedicated API currently doesn’t exist, but I don’t see any reason why we could/shouldn’t add one.

[stefankoegl]

Here's a short summary of how I would approach this.

Overview

I'd suggest to implement an interface that accepts a URL and parses / creates the podcast asynchronously. In this way we can delay creating the podcast until after the feed has been parsed, and avoid to create podcasts that are actually empty.

HTTP Interface

Request

POST /api/2/podcasts/create

{
  url: "http://www.example.com/feed.rss"
}

Authentication does not seem to be necessary.

Processing

Check if a podcast for the given URL already exists. If so, redirect to it (see Retrieve Podcast Data). If not, accept the URL for processing.

Response

• 303 See Other
• 202 Accepted
• Location header pointing to a podcast (for 303, see Retrieve Podcast Data) or a job status object (for 202), eg /api/2/task/<id> where is the Celery task id.

Request Job Status

Returns the celery task id. When the job finished successfully it contains a link to the podcast (as above).

If it finished unsuccessfully (because the URL was not a feed), it can contain a 4xx status code and a respective error message.

GET /api/2/task/<id>

200 OK

{
  id: "<id>",
  type: "create-podcast",
  url: "<url>",
  status: "pending",

  # successful
  status: "successful",
  podcast: "/api/2/data/podcast.json?url=<url>",

  # unsuccessful
  status: "unsuccessful",
  error: "feed could not be parsed"
}

Implementation

I'd implement the API views in mygpo/api/advanced/directory.py.

The function for parsing a podcast in a celery task is mygpo.data.tasks.update_podcasts, and can be called as update_podcasts.delay([podcast_url]). It returns a celery task result.

Documentation

The API should be documented in mygpo/doc/api/reference/directory.rst.

[nico-stefani]

I'd like to contribute with this!

[stefankoegl]

@Nicolas471, that would be great! Please feel free to go ahead and submit a pull request. I am happy to also review partially finished changes to guide you along the way. If there's anything you need, please let me know!

[SiqingYu]

• API for adding new podcast. by SiqingYu · Pull Request API for adding new podcast. #328 · gpodder/mygpo
• Tests for adding podcast API by SiqingYu · Pull Request Tests for adding podcast API [WIP] #336 · gpodder/mygpo

• API views
• Pass CI builds
• Testing
• Read the Docs update, including API changes
• Check edge case - Podcast URL not exist
• Check edge case - Podcast XML format error
• Code reviews

[stefankoegl]

I'd suggest to include functional code, tests, documentation, etc all in one pull request. It might get a bit longer but it will be easier to keep track of things that way. Also you can make sure that things are complete (ie docs or tests might be forgotten after the code has been merged).

[SiqingYu]

@stefankoegl Thanks for your advice. The previous PR has been merged, so I had to open a new PR. Next time I'll tick the boxes before opening the PR.