doc/api/reference/podcastlists.rst

   1 Podcast Lists API
   2 =================
   3
   4 **TODO: this has just been copied from API 2 -- this needs review**
   5
   6 **Podcast Lists** are used to collect podcasts about some topics. On the
   7 website, podcast lists are available at https://gpodder.net/lists/
   8
   9 Resources
  10 ---------
  11
  12 The Podcast Lists API defines the following resources ::
  13
  14     /user/<username>/lists/create
  15     /user/<username>/lists
  16     /user/<username>/list/<list-name>
  17
  18
  19 Creating a Podcast List
  20 -----------------------
  21
  22 Create a Podcast List ::
  23
  24     POST /user/<username>/lists/create?title=<url-encoded title>
  25     The list content is sent in the request body
  26
  27     requires authenticaton
  28
  29 The server then generates a short name for the list from the title given in the
  30 Request. For example, from the title "My Python Podcasts" the name
  31 "my-python-podcasts" would be generated.
  32
  33 Possible Responses
  34
  35 * 409 Conflict: if the the user already has a podcast list with the (generated) name
  36 * 303 See Other: the podcast list has been created at the URL given in the Location header
  37
  38
  39 List the Podcast Lists of a User
  40 --------------------------------
  41 List User's Lists ::
  42
  43     GET /user/<username>/lists
  44
  45
  46 Possible Responses
  47
  48 * 200 OK, the list of lists in the format given below
  49
  50 Response ::
  51
  52     [
  53         {"title": "My Python Podcasts", "name": "my-python-podcasts", "web": "http://gpodder.net/user/<username>/lists/my-python-podcasts" }
  54     ]
  55
  56
  57 Retrieve Podcast List
  58 ---------------------
  59
  60 Retrieve a Podcast List ::
  61
  62     GET /user/<username>/list/<list-name>
  63
  64
  65 Possible Responses
  66
  67 * 404 Not Found if there is no list with the given name
  68 * 200 OK and the podcast list in the given format
  69
  70
  71 Update
  72 ------
  73
  74 Update a Podcast List::
  75
  76     PUT /user/<username>/list/<list-name>
  77
  78 requires authentication
  79
  80
  81 Possible Responses
  82
  83 * 404 Not Found if there is no list with the given name
  84 * 204 No Content If the podcast list has been created / updated
  85
  86
  87 Delete a Podcast List
  88 ---------------------
  89
  90 Delete a Podcast List ::
  91
  92     DELETE /user/<username>/list/<list-name>
  93
  94 requires authentication
  95
  96 Possible Responses
  97
  98 * 404 Not Found if there is no podcast list with the given name
  99 * 204 No Content if the list has been deleted.