doc/api/reference/podcastlists.rst

   1 Podcast Lists API
   2 =================
   3
   4 Podcast Lists are used to collect podcasts about one topic. On the website,
   5 podcast lists are available at https://gpodder.net/lists/
   6
   7
   8 Create Podcast List
   9 -------------------
  10
  11 ..  http:post:: /api/2/lists/(username)/create.(format)
  12     :synopsis: create a new podcast list
  13
  14     * requires authenticaton
  15     * since 2.10
  16
  17     :query title: url-encoded title
  18     :param username: username for which a new podcast list should be created
  19     :param format: see :ref:`formats`
  20
  21     The list content is sent in the request body, in the format indicates by
  22     the format extension
  23
  24     The server then generates a short name for the list from the title given in
  25     the Request. For example, from the title "My Python Podcasts" the name
  26     "my-python-podcasts" would be generated.
  27
  28     :status 409: if the the user already has a podcast list with the
  29                  (generated) name
  30     :status 303: the podcast list has been created at the URL given in the
  31                  :http:header:`Location` header
  32
  33
  34 Get User's Lists
  35 ----------------
  36
  37 ..  http:get:: /api/2/lists/(username).json
  38     :synopsis: get a user's podcast lists
  39
  40     * since 2.10
  41
  42     **Example response**:
  43
  44     .. sourcecode:: http
  45
  46         HTTP/1.1 200 OK
  47
  48         [
  49             {
  50                 "title": "My Python Podcasts",
  51                 "name": "my-python-podcasts",
  52                 "web": "http://gpodder.net/user/a-user/lists/my-python-podcasts"
  53             }
  54         ]
  55
  56     :status 200: the list of lists is returned
  57     :status 404: the user was not found
  58
  59
  60 Get a Podcast List
  61 ------------------
  62
  63 ..  http:get:: /api/2/lists/(username)/list/(listname).(format)
  64     :synopsis: get a podcast list
  65
  66     * since 2.10
  67
  68     :param username: username to which the list belongs
  69     :param listname: name of the requested podcast list
  70     :param format: see :ref:`formats`
  71     :status 200: the podcast list is returned in in the requested format
  72     :status 404: if the user or the list do not exist
  73
  74
  75 Update a Podcast List
  76 ---------------------
  77
  78 ..  http:put:: /api/2/lists/(username)/list/(listname).(format)
  79     :synopsis: update a podcast list
  80
  81     * requires authentication
  82     * since 2.10
  83
  84     :param username: username to which the list belongs
  85     :param listname: name of the requested podcast list
  86     :param format: see :ref:`formats`
  87     :status 404: if the user or the list do not exist
  88     :status 204: if the podcast list has been created / updated
  89
  90
  91 Delete a Podcast List
  92 ---------------------
  93
  94 ..  http:delete:: /api/2/lists/(username)/list/(listname).(format)
  95     :synopsis: delete a podcast list
  96
  97     * requires authentication
  98     * since 2.10
  99
 100     :param username: username to which the list belongs
 101     :param listname: name of the requested podcast list
 102     :param format: see :ref:`formats`
 103     :status 404: if the user or the list do not exist
 104     :status 204: if the podcast list has been deleted