api: Extend documentation a bit.

(imported from commit fd435286e12ffebad8476cc8005303b2d8d70fd9)

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.

examples/send-message

@@ -30,7 +30,7 @@ usage = """send-message [options] <recipient>
 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')