4 **TODO: this has just been copied from API 2 -- this needs review**
6 **Podcast Lists** are used to collect podcasts about some topics. On the
7 website, podcast lists are available at https://gpodder.net/lists/
12 The Podcast Lists API defines the following resources ::
14 /user/{username}/lists/create
15 /user/{username}/lists
16 /user/{username}/list/{listname}
19 Creating a Podcast List
20 -----------------------
22 A podcast list can be created by submitting a list of podcasts to the API.
24 Requires authentication.
29 * **title**: The title of the list (mandatory)
35 Create a Podcast List ::
37 POST /user/{username}/lists/create
38 Content-Tpe: application/json
41 "title": "My Tech News",
43 { "url": "http://example.com/feed.xml" },
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.
55 If the podcast list has been created successfully, ``303 See Other`` is
59 Location: /3/user/yourusername/list/yourlistname
61 The list can then be retrieved using a ``GET`` request.
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. ::
67 "message": "list already exists",
71 code: "duplicate_list_name"
77 List the Podcast Lists of a User
78 --------------------------------
86 GET /user/{username}/lists
87 Content-Tpe: application/json
93 If the user exists, his/her podcast lists are returned. ::
96 Content-Tpe: application/json
101 "title": "My Python Podcasts",
102 "name": "my-python-podcasts",
103 "web": "http://gpodder.net/user/username/lists/my-python-podcasts"
106 "username": "username"
109 If the user does not exist, ``404 Not Found`` is returned. ::
112 Content-Tpe: application/json
115 "message": "user does not exist",
119 code: "user_does_not_exist"
125 Retrieve Podcast List
126 ---------------------
131 Retrieve a Podcast List ::
133 GET /user/{username}/list/{listname}
134 Content-Tpe: application/json
140 The podcast list is returned. ::
143 Content-Tpe: application/json
146 "title": "My Tech News",
147 "name": "my-tech-news",
149 { "url": "http://example.com/feed.xml" },
152 "username": "username",
156 If either the user or the podcast list could not be found ``404 Not Found`` is
160 Content-Tpe: application/json
163 "message": "podcast list does not exist",
167 code: "podcastlist_does_not_exist"
179 Update a Podcast List::
181 PUT /user/{username}/list/{listname}
182 Content-Tpe: application/json
185 "title": "My Tech News",
186 "name": "my-tech-news2",
188 { "url": "http://example.org/feed-mp3.xml" },
193 requires authentication
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
205 Delete a Podcast List
206 ---------------------
211 Delete a Podcast List ::
213 DELETE /user/{username}/list/{listname}
215 requires authentication
221 If the update was successful, ``204 No Content`` is returned. ::
225 * 404 Not Found if there is no podcast list with the given name