update podcast list API draft
authorStefan Kögl <stefan@skoegl.net>
Sat, 13 Jul 2013 20:26:23 +0000 (13 22:26 +0200)
committerStefan Kögl <stefan@skoegl.net>
Sat, 13 Jul 2013 20:26:23 +0000 (13 22:26 +0200)
doc/api/reference/general.rst
doc/api/reference/podcastlists.rst

index fcc10d1..1de5f6a 100644 (file)
@@ -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.
index 5e56c90..c4f1805 100644 (file)
@@ -11,73 +11,191 @@ Resources
 
 The Podcast Lists API defines the following resources ::
 
-    /user/<username>/lists/create
-    /user/<username>/lists
-    /user/<username>/list/<list-name>
+    /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/<username>/lists/create?title=<url-encoded 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/<username>/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/<username>/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/<username>/list/<list-name>
+    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/<username>/list/<list-name>
+    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/<username>/list/<list-name>
+    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.