From 28334936a24c266c4bc5d614ef4972a4ff2f399e Mon Sep 17 00:00:00 2001 From: Anita Kuno Date: Wed, 6 Jul 2016 17:34:01 -0400 Subject: [PATCH] Add example commands for the Subscriptions 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 Subscriptions section of the api documentation. Change-Id: Ic075f3680da09fabea6ccbe622db98c2925c6b8f --- storyboard/api/v1/subscriptions.py | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/storyboard/api/v1/subscriptions.py b/storyboard/api/v1/subscriptions.py index e7df08a2..507c3e91 100644 --- a/storyboard/api/v1/subscriptions.py +++ b/storyboard/api/v1/subscriptions.py @@ -69,6 +69,11 @@ class SubscriptionsController(rest.RestController): def get_one(self, subscription_id): """Retrieve a specific subscription record. + Example:: + + curl https://my.example.org/api/v1/subscriptions/4 \\ + -H 'Authorization: Bearer MY_ACCESS_TOKEN' + :param subscription_id: The unique id of this subscription. """ @@ -87,7 +92,12 @@ class SubscriptionsController(rest.RestController): wtypes.text, wtypes.text) def get(self, marker=None, limit=None, target_type=None, target_id=None, user_id=None, sort_field='id', sort_dir='asc'): - """Retrieve a list of subscriptions. + """Retrieve a list of subscriptions for the authorized user. + + Example:: + + curl https://my.example.org/api/v1/subscriptions \\ + -H 'Authorization: Bearer MY_ACCESS_TOKEN' :param marker: The resource id where the page should begin. :param limit: The number of subscriptions to retrieve. @@ -138,6 +148,14 @@ class SubscriptionsController(rest.RestController): @wsme_pecan.wsexpose(Subscription, body=Subscription) def post(self, subscription): """Create a new subscription. + Note: target_id is the same value as the story_id of a story. + + Example:: + + curl https://my.example.org/api/v1/subscriptions \\ + -H 'Authorization: Bearer MY_ACCESS_TOKEN' \\ + -H 'Content-Type: application/json;charset=UTF-8' \\ + --data-binary '{"target_type":"story","target_id":8}' :param subscription: A subscription within the request body. """ @@ -182,6 +200,11 @@ class SubscriptionsController(rest.RestController): def delete(self, subscription_id): """Delete a specific subscription. + Example:: + + curl https://my.example.org/api/v1/subscriptions/10 -X DELETE \\ + -H 'Authorization: Bearer MY_ACCESS_TOKEN' + :param subscription_id: The unique id of the subscription to delete. """ subscription = subscription_api.subscription_get(subscription_id)