Adds note about Promises to the REST API docs

README.md

@@ -114,6 +114,28 @@ client.post('statuses/update', {status: 'I Love Twitter'},  function(error, twee
 });
 ```
 
+### Promises
+
+The REST API convenience methods will also return Promises if:
+
+1.  A callback is omitted
+2.  Promise's are available.
+
+If those two conditions are met, the above example becomes:
+
+```javascript
+client.post('statuses/update', {status: 'I Love Twitter'})
+  .then(function (tweet) {
+    console.log(tweet);
+  })
+  .catch(function (error) {
+    throw error;
+  })
+```
+
+Note, the raw `response` object returned by the Request module is not passed through
+the fulfilled promise.  If you require this, please use the callback pattern.
+
 ## Streaming API
 
 Using the `stream` convenience method, you to open and manipulate data via a stream piped directly from one of the streaming API's. Let's see who is talking about javascript: