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/{listname}
  17
  18
  19 Creating a Podcast List
  20 -----------------------
  21
  22 A podcast list can be created by submitting a list of podcasts to the API.
  23
  24 Requires authentication.
  25
  26 Parameters
  27 ^^^^^^^^^^
  28
  29 * **title**: The title of the list (mandatory)
  30
  31
  32 Request
  33 ^^^^^^^
  34
  35 Create a Podcast List ::
  36
  37     POST /user/{username}/lists/create
  38     Content-Tpe: application/json
  39
  40     {
  41         "title": "My Tech News",
  42         "podcasts": [
  43             { "url": "http://example.com/feed.xml" },
  44             ...
  45         ]
  46     }
  47
  48 The server then generates a short name for the list from the title given in the
  49 request. For example, from the title "My Python Podcasts" the name
  50 "my-python-podcasts" would be generated.
  51
  52 Responses
  53 ^^^^^^^^^
  54
  55 If the podcast list has been created successfully, ``303 See Other`` is
  56 returned. ::
  57
  58     303 See Other
  59     Location: /3/user/yourusername/list/yourlistname
  60
  61 The list can then be retrieved using a ``GET`` request.
  62
  63 If the list could not be created, an error code is returned. If another list
  64 with the same (generated) name exists, ``409 Conflict`` is returned. ::
  65
  66     {
  67         "message": "list already exists",
  68         "errors": [
  69             {
  70                 field: "/title",
  71                 code: "duplicate_list_name"
  72             }
  73         ]
  74     }
  75
  76
  77 List the Podcast Lists of a User
  78 --------------------------------
  79
  80
  81 Request
  82 ^^^^^^^
  83
  84 List User's Lists ::
  85
  86     GET /user/{username}/lists
  87     Content-Tpe: application/json
  88
  89
  90 Response
  91 ^^^^^^^^
  92
  93 If the user exists, his/her podcast lists are returned. ::
  94
  95     200 OK
  96     Content-Tpe: application/json
  97
  98     {
  99         "podcastlists": [
 100             {
 101                 "title": "My Python Podcasts",
 102                 "name": "my-python-podcasts",
 103                 "web": "http://gpodder.net/user/username/lists/my-python-podcasts"
 104             }
 105         ],
 106         "username": "username"
 107     }
 108
 109 If the user does not exist, ``404 Not Found`` is returned. ::
 110
 111     404 Not Found
 112     Content-Tpe: application/json
 113
 114     {
 115         "message": "user does not exist",
 116         "errors": [
 117             {
 118                 field: "?username",
 119                 code: "user_does_not_exist"
 120             }
 121         ]
 122     }
 123
 124
 125 Retrieve Podcast List
 126 ---------------------
 127
 128 Request
 129 ^^^^^^^
 130
 131 Retrieve a Podcast List ::
 132
 133     GET /user/{username}/list/{listname}
 134     Content-Tpe: application/json
 135
 136
 137 Response
 138 ^^^^^^^^
 139
 140 The podcast list is returned. ::
 141
 142     200 OK
 143     Content-Tpe: application/json
 144
 145     {
 146         "title": "My Tech News",
 147         "name": "my-tech-news",
 148         "podcasts": [
 149             { "url": "http://example.com/feed.xml" },
 150             ...
 151         ],
 152         "username": "username",
 153     }
 154
 155
 156 If either the user or the podcast list could not be found ``404 Not Found`` is
 157 returned. ::
 158
 159     404 Not Found
 160     Content-Tpe: application/json
 161
 162     {
 163         "message": "podcast list does not exist",
 164         "errors": [
 165             {
 166                 field: "?listname",
 167                 code: "podcastlist_does_not_exist"
 168             }
 169         ]
 170     }
 171
 172
 173 Update
 174 ------
 175
 176 Request
 177 ^^^^^^^
 178
 179 Update a Podcast List::
 180
 181     PUT /user/{username}/list/{listname}
 182     Content-Tpe: application/json
 183
 184     {
 185         "title": "My Tech News",
 186         "name": "my-tech-news2",
 187         "podcasts": [
 188             { "url": "http://example.org/feed-mp3.xml" },
 189             ...
 190         ]
 191     }
 192
 193 requires authentication
 194
 195
 196 Response
 197 ^^^^^^^^
 198
 199 Possible Responses
 200
 201 * 404 Not Found if there is no list with the given name
 202 * 204 No Content If the podcast list has been created / updated
 203
 204
 205 Delete a Podcast List
 206 ---------------------
 207
 208 Request
 209 ^^^^^^^
 210
 211 Delete a Podcast List ::
 212
 213     DELETE /user/{username}/list/{listname}
 214
 215 requires authentication
 216
 217
 218 Response
 219 ^^^^^^^^
 220
 221 If the update was successful, ``204 No Content`` is returned. ::
 222
 223     204 No Content
 224
 225 * 404 Not Found if there is no podcast list with the given name