search

gpodder / mygpo

The gpodder.net webservice
http://gpodder.net/
GNU Affero General Public License v3.0
273 stars 85 forks source link

Add new podcast by API #219

Open geraldo opened 5 years ago

geraldo commented 5 years ago

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 commented 5 years ago

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 commented 4 years ago

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

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 commented 4 years ago

I'd like to contribute with this!

stefankoegl commented 4 years ago

@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 commented 4 years ago
stefankoegl commented 4 years ago

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 commented 4 years ago

@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.