From ebf009b232d823d99d9410a3f5a5a58b4fb14ce7 Mon Sep 17 00:00:00 2001 From: Tim Abbott Date: Tue, 27 Nov 2012 11:19:05 -0500 Subject: [PATCH] api: Extend documentation a bit. (imported from commit fd435286e12ffebad8476cc8005303b2d8d70fd9) --- README | 46 +++++++++++++++++++++++++++++++++++++++++++ examples/send-message | 2 +- 2 files changed, 47 insertions(+), 1 deletion(-) diff --git a/README b/README index dec633a..2e30e01 100644 --- a/README +++ b/README @@ -1,4 +1,50 @@ +#### Dependencies + The Humbug API Python bindings require the following Python libraries: * simplejson * requests (version >= 0.12) + +#### Using the API + +For now, the only fully supported API operation is sending a message. +The other API queries work, but are under active development, so +please make sure we know you're using them so that we can notify you +as we make any changes to them. + +The easiest way to use these API bindings is to base your tools off +of the example tools under api/examples in this distribution. + +If you place your API key in ~/.humbug-api-key the Python API +bindings will automatically read it in. You can obtain your Humbug +API key from the Humbug settings page. + +A typical simple bot sending API messages will look as follows: + +At the top of the file: + + # Make sure the Humbug API distribution's root directory is in sys.path, then: + import api.common + humbug_client = api.common.HumbugAPI(email="your_email@example.com") + +When you want to send a message: + + message = { + "type": "stream", + "to": ["support"], + "subject": "your subject", + "content": "your content", + } + humbug_client.send_message(message) + +Additional examples: + + client.send_message({'type': 'stream', 'content': 'Humbug rules!', + 'subject': 'feedback', 'to': ['support']}) + client.send_message({'type': 'private', 'content': 'Humbug rules!', + 'to': ['user1@example.com', 'user2@example.com']}) + +send_message() returns a dict guaranteed to contain the following +keys: msg, result. For successful calls, result will be "success" and +msg will be the empty string. On error, result will be "error" and +msg will describe what went wrong. diff --git a/examples/send-message b/examples/send-message index 5f789ae..1d83bb8 100755 --- a/examples/send-message +++ b/examples/send-message @@ -30,7 +30,7 @@ usage = """send-message [options] Sends a test message to the specified recipients. Example: send-message --sender=you@example.com --type=stream commits -Example: send-message --sender=you@example.com --site=https://zephyr.humbughq.com iago@humbughq.com +Example: send-message --sender=you@example.com --site=https://zephyr.humbughq.com user1@example.com user2@example.com """ parser = optparse.OptionParser(usage=usage) parser.add_option('--api-key')