First pass at HTTP docs.

docs/client/api.html

@@ -1355,6 +1355,85 @@ <h2 id="meteor_deps"><span>Meteor.deps</span></h2>
 then restores its previous value.)
 
 
+<h2 id="meteor_http"><span>Meteor.http</span></h2>
+
+{{> api_box httpcall}}
+
+This function initiates an HTTP request to a remote server. It returns
+a result object with the contents of the HTTP response. The result
+object is detailed below.
+
+On the server, this function can be run synchronously by omitting
+the callback argument. In this case, the results are returned
+to the caller once the request completes. This is useful when making
+server-to-server HTTP API calls from with Meteor methods. You can easily
+delay return method success or failure to the client until after the HTTP
+call has finished. In this case, consider running
+[`this.unblock()`](#method_unblock) to allow other methods to start.
+
+The `url` argument can begin with `"http://"` or `"https://"`. On the
+client, you can also use relative URLs, on the server only absolute URLs
+are allowed. `url` can include a query string, but it will be
+overwritten if the `query` option is passed. The `params` option will be
+encoded and either added to the URL (GET requests and POST requests that
+already have `content` specified) or to the body of the request (POST
+requests without `content` specified)
+
+The callback receives two arguments, `error` and `result`.  The `error`
+argument will contain an Error if the request fails in any way,
+including a bad HTTP status code. The result object is always
+defined. When run in synchronous mode, the `result` is returned from the
+function, and the `error` value is a stored as a property in `result`.
+
+Contents of the result object:
+
+<dl class="objdesc">
+
+<dt><span class="name">statusCode</span>
+  <span class="type">Number or null</span></dt>
+<dd>Numeric HTTP result status code, or null on error.</dd>
+
+<dt><span class="name">headers()</span>
+  <span class="type">Object</span></dt>
+<dd>Return a dictionary of HTTP headers from the response.</dd>
+
+<dt><span class="name">content()</span>
+  <span class="type">String</span></dt>
+<dd>Return the body of the HTTP response as a string.</dd>
+
+<dt><span class="name">data()</span>
+  <span class="type">Object</span></dt>
+<dd>Return the body of the document parsed as a JSON object</dd>
+
+<dt><span class="name">error</span>
+  <span class="type">Error</span></dt>
+<dd>Error object if the request failed. Matches the `error` callback parameter.</dd>
+
+
+</dl>
+
+Example server method:
+
+    Meteor.methods({check_twitter: function (user_id) {
+      this.unblock();
+      var result = Meteor.http.call("GET", "http://api.twitter.com/xxx",
+                                    {params: {user: user_id}});
+      if (result.statusCode === 200)
+         return true
+      return false;
+    }});
+
+Example asynchronous HTTP call:
+
+    Meteor.http.call("POST", "http://api.twitter.com/xxx",
+                     {data: {some: "json", stuff: 1}},
+                     function (error, result) {
+                       if (result.statusCode === 200) {
+                         Session.set("twizzled", true);
+                       }
+                     });
+
+
 {{/better_markdown}}
 </template>
 

docs/client/api.js

@@ -743,3 +743,52 @@ Template.api.equals = {
      descr: "The value to test against"}
   ]
 };
+
+Template.api.httpcall = {
+  id: "meteor_http_call",
+  name: "Meteor.http.call(method, url, [options], [asyncCallback])",
+  locus: "Anywhere",
+  descr: ["Perform an outbound HTTP request."],
+  args: [
+    {name: "method",
+     type: "String",
+     descr: 'The HTTP method to use, e.g. "GET" or "POST".'},
+    {name: "url",
+     type: "String",
+     descr: 'The URL to retrieve.'},
+    {name: "asyncCallback",
+     type: "Function",
+     descr: "Optional callback.  If passed, the method runs asynchronously, instead of synchronously, and calls asyncCallback.  On the client, this callback is required."
+    }
+  ],
+  options: [
+    {name: "content",
+     type: "String",
+     descr: "HTTP request body, as a raw string."
+},
+    {name: "data",
+     type: "Object",
+     descr: "JSON-able object, encoded and placed in HTTP request body. Overwrites `content`."},
+    {name: "query",
+     type: "String",
+     descr: "Query string. If given, overwrites any query string in `url`"},
+    {name: "params",
+     type: "Object",
+     descr: "Parameters are encoded and placed in the URL for GETs, or the body for POSTs"
+    },
+    {name: "auth",
+     type: "String",
+     descr: 'HTTP basic authentication string, e.g. `"username:password"`'},
+    {name: "headers",
+     type: "Object",
+     descr: "Dictionary of values to place in HTTP headers."},
+    {name: "timeout",
+     type: "Number",
+     descr: "Fail the request if it takes longer that `timeout` milliseconds."},
+    {name: "followRedirects",
+     type: "Boolean",
+    descr: "Whether or not to follow HTTP redirects. Defaults to true. Can not be disabled on the client."}
+  ]
+};
+
+

docs/client/docs.js

@@ -162,6 +162,10 @@ var toc = [
     //     {instance: "env_var", name: "withValue", id: "env_var_withvalue"},
     //     {instance: "env_var", name: "bindEnvironment", id: "env_var_bindenvironment"}
     //   ]
+    ],
+
+    "Meteor.http", [
+      "Meteor.http.call"
     ]
   ],