opendev
/
storyboard
Code Issues Proposed changes

Add example commands for the Worklists api 

Currently the api documentation does not include example commands.
It would be very friendly for our users to have some example
commands to follow and use the api.

This patch adds examples to the Worklists section of the api documentation.

Co-Authored-By: Zara <zara.zaimeche@codethink.co.uk>
Change-Id: I9b043bf0f37025cdd3ea422a000d8acb7f78e8d7
This commit is contained in:
Anita Kuno 2016-07-11 14:28:16 -04:00
parent aba5c32fbd
commit 6a5ec7a0f2
1 changed files with 76 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
storyboard/api/v1/worklists.py
View File

@ -44,6 +44,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.
"""
@ -61,6 +66,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.
@ -78,6 +87,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.
@ -99,6 +112,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.
@ -120,6 +137,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.
"""
@ -143,6 +164,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.
@ -164,6 +189,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.
@ -185,6 +214,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.
@ -206,6 +239,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.
"""
@ -236,6 +273,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").
@ -271,6 +312,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.
@ -321,6 +366,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.
@ -345,6 +394,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.
"""
@ -372,6 +425,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.
@ -466,6 +523,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.
"""
@ -514,6 +578,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.
@ -547,6 +615,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.