From 7713169721f326e940458ca16b9d4fe2b85faf2e Mon Sep 17 00:00:00 2001
From: reality <tinmachin3@gmail.com>
Date: Fri, 17 May 2013 09:59:25 +0000
Subject: [PATCH] help for api module [#352]

---
 modules/api/README.md   | 45 +++++++++++++++++++++++++++++++++++++++++
 modules/web/config.json |  2 +-
 2 files changed, 46 insertions(+), 1 deletion(-)
 create mode 100644 modules/api/README.md

diff --git a/modules/api/README.md b/modules/api/README.md
new file mode 100644
index 0000000..4ebb156
--- /dev/null
+++ b/modules/api/README.md
@@ -0,0 +1,45 @@
+## API
+
+Creates external REST APIs for module API functions.
+
+### Description
+
+This module uses the web module to expose module API functionality externally
+through a REST API. As it stands, it's only really useful for viewing various
+information returned by API functions, as there is no system for API keys or
+anything like that to protect against misuse of functionality which modifies
+data.
+
+To externalise an API function, two properties must be set on a particular API
+function, like so:
+
+    api['resolveUser'].external = true;
+    api['resolveUser'].extMap = [ 'server', 'nick', 'callback' ];
+
+The first, 'external' flag simply lets the API module know that this function is
+intended to be exposed externally - and functions will always be considered not
+to be externally available unless this flag is explicitly set.
+
+The second is a mapping of parameters to the module. This should match the
+function prototype given when the function is declared (unfortunately these
+can't be mapped automatically because the closure use means we get 'native code'
+returned and can't scan the function headers for the parameter names).
+
+Then, to access this function remotely we can simply make a GET request to the
+web counterpart to the internal API function path. So, internally you'd access 
+the resolveUser function at _dbot.api.users.resolveUser_, we can get to it
+externally with _/api/users/resolveUser_ - supplying parameters as they are
+named in the extMap.
+
+The response to the API call will be given in the form of JSON:
+
+    {
+        err: Error, such as 'API function not enabled for external access'
+        data: API call response
+    }
+
+If there is a _callback_ parameter named in the extMap, then the API module
+automatically hijacks this parameter and uses the data it's called with to
+supply the response to the API call with data. If there is no callback
+parameter, then it's a blocking API request and the response will be the return
+value of the call.
diff --git a/modules/web/config.json b/modules/web/config.json
index e6b635e..d49b7e6 100644
--- a/modules/web/config.json
+++ b/modules/web/config.json
@@ -1,6 +1,6 @@
 {
     "webHost": "nourishedcloud.com",
-    "webPort": 8080,
+    "webPort": 8050,
     "externalPath": false,
     "help": "https://github.com/reality/depressionbot/blob/master/modules/web/README.md"
 }