From 828b4be3d4af64c4ad26de9ec2c26fec1b331763 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Stefan=20K=C3=B6gl?= Date: Sat, 13 Jul 2013 22:26:23 +0200 Subject: [PATCH] update podcast list API draft --- doc/api/reference/general.rst | 3 + doc/api/reference/podcastlists.rst | 176 +++++++++++++++++++++++++++++++------ 2 files changed, 154 insertions(+), 25 deletions(-) diff --git a/doc/api/reference/general.rst b/doc/api/reference/general.rst index fcc10d1d..1de5f6af 100644 --- a/doc/api/reference/general.rst +++ b/doc/api/reference/general.rst @@ -92,6 +92,9 @@ The ``code`` describes the actual error. The following error codes are defined: * ``ìnvalid_url``: The provided values is not a valid URL. * ``parameter_missing``: A mandatory parameter was not provided. +* ``duplicate_list_name``: A podcast list with the same name already exists. +* ``user_does_not_exist``: the specified user does not exist. +* ``podcastlist_does_not_exist``: the specified podcast list does not exist. Error codes may be added on demand. Clients should therefore expect and accept arbitrary string values. diff --git a/doc/api/reference/podcastlists.rst b/doc/api/reference/podcastlists.rst index 5e56c90d..c4f18051 100644 --- a/doc/api/reference/podcastlists.rst +++ b/doc/api/reference/podcastlists.rst @@ -11,73 +11,191 @@ Resources The Podcast Lists API defines the following resources :: - /user//lists/create - /user//lists - /user//list/ + /user/{username}/lists/create + /user/{username}/lists + /user/{username}/list/{listname} Creating a Podcast List ----------------------- +A podcast list can be created by submitting a list of podcasts to the API. + +Requires authentication. + +Parameters +^^^^^^^^^^ + +* **title**: The title of the list (mandatory) + + +Request +^^^^^^^ + Create a Podcast List :: - POST /user//lists/create?title= - The list content is sent in the request body + POST /user/{username}/lists/create + Content-Tpe: application/json - requires authenticaton + { + "title": "My Tech News", + "podcasts": [ + { "url": "http://example.com/feed.xml" }, + ... + ] + } The server then generates a short name for the list from the title given in the -Request. For example, from the title "My Python Podcasts" the name +request. For example, from the title "My Python Podcasts" the name "my-python-podcasts" would be generated. -Possible Responses +Responses +^^^^^^^^^ + +If the podcast list has been created successfully, ``303 See Other`` is +returned. :: + + 303 See Other + Location: /3/user/yourusername/list/yourlistname -* 409 Conflict: if the the user already has a podcast list with the (generated) name -* 303 See Other: the podcast list has been created at the URL given in the Location header +The list can then be retrieved using a ``GET`` request. + +If the list could not be created, an error code is returned. If another list +with the same (generated) name exists, ``409 Conflict`` is returned. :: + + { + "message": "list already exists", + "errors": [ + { + field: "/title", + code: "duplicate_list_name" + } + ] + } List the Podcast Lists of a User -------------------------------- + + +Request +^^^^^^^ + List User's Lists :: - GET /user//lists + GET /user/{username}/lists + Content-Tpe: application/json -Possible Responses +Response +^^^^^^^^ + +If the user exists, his/her podcast lists are returned. :: + + 200 OK + Content-Tpe: application/json + + { + "podcastlists": [ + { + "title": "My Python Podcasts", + "name": "my-python-podcasts", + "web": "http://gpodder.net/user/username/lists/my-python-podcasts" + } + ], + "username": "username" + } -* 200 OK, the list of lists in the format given below +If the user does not exist, ``404 Not Found`` is returned. :: -Response :: + 404 Not Found + Content-Tpe: application/json - [ - {"title": "My Python Podcasts", "name": "my-python-podcasts", "web": "http://gpodder.net/user//lists/my-python-podcasts" } - ] + { + "message": "user does not exist", + "errors": [ + { + field: "?username", + code: "user_does_not_exist" + } + ] + } Retrieve Podcast List --------------------- +Request +^^^^^^^ + Retrieve a Podcast List :: - GET /user//list/ + GET /user/{username}/list/{listname} + Content-Tpe: application/json -Possible Responses +Response +^^^^^^^^ -* 404 Not Found if there is no list with the given name -* 200 OK and the podcast list in the given format +The podcast list is returned. :: + + 200 OK + Content-Tpe: application/json + + { + "title": "My Tech News", + "name": "my-tech-news", + "podcasts": [ + { "url": "http://example.com/feed.xml" }, + ... + ], + "username": "username", + } + + +If either the user or the podcast list could not be found ``404 Not Found`` is +returned. :: + + 404 Not Found + Content-Tpe: application/json + + { + "message": "podcast list does not exist", + "errors": [ + { + field: "?listname", + code: "podcastlist_does_not_exist" + } + ] + } Update ------ +Request +^^^^^^^ + Update a Podcast List:: - PUT /user//list/ + PUT /user/{username}/list/{listname} + Content-Tpe: application/json + + { + "title": "My Tech News", + "name": "my-tech-news2", + "podcasts": [ + { "url": "http://example.org/feed-mp3.xml" }, + ... + ] + } requires authentication +Response +^^^^^^^^ + Possible Responses * 404 Not Found if there is no list with the given name @@ -87,13 +205,21 @@ Possible Responses Delete a Podcast List --------------------- +Request +^^^^^^^ + Delete a Podcast List :: - DELETE /user//list/ + DELETE /user/{username}/list/{listname} requires authentication -Possible Responses + +Response +^^^^^^^^ + +If the update was successful, ``204 No Content`` is returned. :: + + 204 No Content * 404 Not Found if there is no podcast list with the given name -* 204 No Content if the list has been deleted. -- 2.11.4.GIT