Merge "Add example commands for the Worklists api"

storyboard/api/v1/worklists.py

@@ -45,6 +45,11 @@ class PermissionsController(rest.RestController):
     def get(self, worklist_id):
         """Get worklist permissions for the current user.
 
+        Example::
+
+          curl https://my.example.org/api/v1/worklists/31/permissions \\
+          -H 'Authorization: Bearer MY_ACCESS_TOKEN'
+
         :param worklist_id: The ID of the worklist.
 
         """
@@ -62,6 +67,10 @@ class PermissionsController(rest.RestController):
     def post(self, worklist_id, permission):
         """Add a new permission to the worklist.
 
+        Example::
+
+          TODO
+
         :param worklist_id: The ID of the worklist.
         :param permission: The dict to use to create the permission.
 
@@ -79,6 +88,10 @@ class PermissionsController(rest.RestController):
     def put(self, worklist_id, permission):
         """Update a permission of the worklist.
 
+        Example::
+
+          TODO
+
         :param worklist_id: The ID of the worklist.
         :param permission: The new contents of the permission.
 
@@ -100,6 +113,10 @@ class FilterSubcontroller(rest.RestController):
     def get_one(self, worklist_id, filter_id):
         """Get a single filter for the worklist.
 
+        Example::
+
+          curl https://my.example.org/api/v1/worklists/49/filters/20
+
         :param worklist_id: The ID of the worklist.
         :param filter_id: The ID of the filter.
 
@@ -121,6 +138,10 @@ class FilterSubcontroller(rest.RestController):
     def get(self, worklist_id):
         """Get filters for an automatic worklist.
 
+        Example::
+
+          curl https://my.example.org/api/v1/worklists/49/filters
+
         :param worklist_id: The ID of the worklist.
 
         """
@@ -144,6 +165,10 @@ class FilterSubcontroller(rest.RestController):
     def post(self, worklist_id, filter):
         """Create a new filter for the worklist.
 
+        Example::
+
+          TODO
+
         :param worklist_id: The ID of the worklist to set the filter on.
         :param filter: The filter to set.
 
@@ -165,6 +190,10 @@ class FilterSubcontroller(rest.RestController):
     def put(self, worklist_id, filter_id, filter):
         """Update a filter on the worklist.
 
+        Example::
+
+          TODO
+
         :param worklist_id: The ID of the worklist.
         :param filter_id: The ID of the filter to be updated.
         :param filter: The new contents of the filter.
@@ -186,6 +215,10 @@ class FilterSubcontroller(rest.RestController):
     def delete(self, worklist_id, filter_id):
         """Delete a filter from a worklist.
 
+        Example::
+
+          TODO
+
         :param worklist_id: The ID of the worklist.
         :param filter_id: The ID of the filter to be deleted.
 
@@ -207,6 +240,10 @@ class ItemsSubcontroller(rest.RestController):
     def get(self, worklist_id):
         """Get items inside a worklist.
 
+        Example::
+
+          curl https://my.example.org/api/v1/worklists/49/items
+
         :param worklist_id: The ID of the worklist.
 
         """
@@ -237,6 +274,10 @@ class ItemsSubcontroller(rest.RestController):
     def post(self, id, item_id, item_type, list_position):
         """Add an item to a worklist.
 
+        Example::
+
+          TODO
+
         :param id: The ID of the worklist.
         :param item_id: The ID of the item.
         :param item_type: The type of the item (i.e. "story" or "task").
@@ -272,6 +313,10 @@ class ItemsSubcontroller(rest.RestController):
             display_due_date=None):
         """Update a WorklistItem.
 
+        Example::
+
+          TODO
+
         This method also updates the positions of other items in affected
         worklists, if necessary.
 
@@ -322,6 +367,10 @@ class ItemsSubcontroller(rest.RestController):
     def delete(self, id, item_id):
         """Remove an item from a worklist.
 
+        Example::
+
+          TODO
+
         :param id: The ID of the worklist.
         :param item_id: The ID of the worklist item to be removed.
 
@@ -347,6 +396,10 @@ class WorklistsController(rest.RestController):
     def get_one(self, worklist_id):
         """Retrieve details about one worklist.
 
+        Example::
+
+          curl https://my.example.org/api/v1/worklists/27
+
         :param worklist_id: The ID of the worklist.
 
         """
@@ -374,6 +427,10 @@ class WorklistsController(rest.RestController):
                 offset=None, limit=None):
         """Retrieve definitions of all of the worklists.
 
+        Example::
+
+          curl https://my.example.org/api/v1/worklists
+
         :param title: A string to filter the title by.
         :param creator_id: Filter worklists by their creator.
         :param project_id: Filter worklists by project ID.
@@ -468,6 +525,13 @@ class WorklistsController(rest.RestController):
     def post(self, worklist):
         """Create a new worklist.
 
+        Example::
+
+          curl https://my.example.org/api/v1/worklists \\
+          -H 'Authorization: Bearer MY_ACCESS_TOKEN' \\
+          -H 'Content-Type: application/json;charset=UTF-8' \\
+          --data-binary '{"title":"create worklist via api"}'
+
         :param worklist: A worklist within the request body.
 
         """
@@ -516,6 +580,10 @@ class WorklistsController(rest.RestController):
     def put(self, id, worklist):
         """Modify this worklist.
 
+        Example::
+
+          TODO
+
         :param id: The ID of the worklist.
         :param worklist: A worklist within the request body.
 
@@ -549,6 +617,14 @@ class WorklistsController(rest.RestController):
     @wsme_pecan.wsexpose(None, int, status_code=204)
     def delete(self, worklist_id):
         """Archive this worklist.
+           Though this uses the DELETE command, the worklist is not deleted.
+           Archived worklists remain viewable at the designated URL, but
+           are not returned in search results nor appear on your dashboard.
+
+        Example::
+
+          curl https://my.example.org/api/v1/worklists/30 -X DELETE \\
+          -H 'Authorization: Bearer MY_ACCESS_TOKEN'
 
         :param worklist_id: The ID of the worklist to be archived.