diff --git a/storyboard/api/v1/stories.py b/storyboard/api/v1/stories.py index ad670a14..14b0e885 100644 --- a/storyboard/api/v1/stories.py +++ b/storyboard/api/v1/stories.py @@ -69,6 +69,10 @@ class StoriesController(rest.RestController): def get_one(self, story_id): """Retrieve details about one story. + Example:: + + curl https://my.example.org/api/v1/stories/11 + :param story_id: An ID of the story. """ story = stories_api.story_get( @@ -91,6 +95,10 @@ class StoriesController(rest.RestController): sort_field='id', sort_dir='asc'): """Retrieve definitions of all of the stories. + Example:: + + curl https://my.example.org/api/v1/stories + :param title: A string to filter the title by. :param description: A string to filter the description by. :param status: Only show stories with this particular status. @@ -165,6 +173,13 @@ class StoriesController(rest.RestController): def post(self, story): """Create a new story. + Example:: + + curl 'https://my.example.org/api/v1/stories' \\ + -H 'Authorization: Bearer MY_ACCESS_TOKEN' \\ + -H 'Content-Type: application/json;charset=UTF-8' \\ + --data-binary '{"title":"Test Story","description":"A test story."}' + :param story: A story within the request body. """ @@ -212,6 +227,13 @@ class StoriesController(rest.RestController): def put(self, story_id, story): """Modify this story. + Example:: + + curl 'https://my.example.org/api/v1/stories/19' -X PUT \\ + -H 'Authorization: Bearer MY_ACCESS_TOKEN' \\ + -H 'Content-Type: application/json;charset=UTF-8' \\ + --data-binary '{"title":"Modified","description":"New description."}' + :param story_id: An ID of the story. :param story: A story within the request body. """ @@ -276,7 +298,12 @@ class StoriesController(rest.RestController): @secure(checks.superuser) @wsme_pecan.wsexpose(wmodels.Story, int, status_code=204) def delete(self, story_id): - """Delete this story. + """Delete this story. This command is only available to Admin users. + + Example:: + + curl 'https://my.example.org/api/v1/stories/5' -X DELETE \\ + -H 'Authorization: Bearer MY_ACCESS_TOKEN' :param story_id: An ID of the story. """ @@ -295,6 +322,10 @@ class StoriesController(rest.RestController): def search(self, q="", marker=None, offset=None, limit=None): """The search endpoint for stories. + Example:: + + curl https://my.example.org/api/v1/stories/search?q=pep8 + :param q: The query string. :return: List of Stories matching the query. """ diff --git a/storyboard/api/v1/tasks.py b/storyboard/api/v1/tasks.py index 76cefb0c..837f3170 100644 --- a/storyboard/api/v1/tasks.py +++ b/storyboard/api/v1/tasks.py @@ -447,6 +447,10 @@ class TasksNestedController(rest.RestController): def get_one(self, story_id, task_id): """Retrieve details about one task. + Example:: + + curl https://my.example.org/api/v1/stories/11/tasks/2691 + :param story_id: An ID of the story. :param task_id: An ID of the task. """ @@ -469,7 +473,11 @@ class TasksNestedController(rest.RestController): project_group_id=None, branch_id=None, milestone_id=None, status=None, priority=None, marker=None, limit=None, sort_field='id', sort_dir='asc', link=None): - """Retrieve definitions of all of the tasks. + """Retrieve definitions of all of the tasks associated with a story. + + Example:: + + curl https://my.example.org/api/v1/stories/11/tasks :param story_id: filter tasks by story ID. :param title: search by task title. @@ -537,6 +545,13 @@ class TasksNestedController(rest.RestController): def post(self, story_id, task): """Create a new task. + Example:: + + curl 'https://my.example.org/api/v1/stories/19/tasks' \\ + -H 'Authorization: Bearer MY_ACCESS_TOKEN' \\ + -H 'Content-Type: application/json;charset=UTF-8' \\ + --data-binary '{"title":"Task Foo","project_id":153,"key":"todo"}' + :param story_id: An ID of the story. :param task: a task within the request body. """ @@ -572,6 +587,13 @@ class TasksNestedController(rest.RestController): def put(self, story_id, task_id, task): """Modify this task. + Example:: + + curl 'https://my.example.org/api/v1/stories/19/tasks/19' -X PUT \\ + -H 'Authorization: Bearer MY_ACCESS_TOKEN' \\ + -H 'Content-Type: application/json;charset=UTF-8' \\ + --data-binary '{"title":"Task Foio","project_id":153,"key":"todo"}' + :param story_id: An ID of the story. :param task_id: An ID of the task. :param task: a task within the request body. @@ -600,6 +622,11 @@ class TasksNestedController(rest.RestController): def delete(self, story_id, task_id): """Delete this task. + Example:: + + curl 'https://my.example.org/api/v1/stories/11/tasks/28' -X DELETE \\ + -H 'Authorization: Bearer MY_ACCESS_TOKEN' + :param story_id: An ID of the story. :param task_id: An ID of the task. """