Update API.md

API.md

@@ -147,16 +147,28 @@ module.exports.create = function (conf, deps, app) {
 ```
 
 Special methods for `app`:
+--------------------------
 
 ### app.handlePromise(request, response, promise, message);
 
 `handlePromise` will respond to the request with the result of `promise` as JSON.
 If there is an error, it will include `message` in order to help you debug.
 
-```
-      req.apiUrlPrefix => https://api.example.com/api/tld.domain.pkg
-      req.experienceId      // the example.com part of https://example.com/foo (or example.com#foo if /foo is part of the app name)
-      req.clientApiUri      // the api.example.com part of https://api.example.com/api/com.example.hello/kv/foo
+Special properties of `request`:
+--------------------------------
+
+```js
+req.apiUrlPrefix                    // This represents the full package path 
+                                    // without any package specific endpoints    
+                                    // i.e. https://api.example.com/api/tld.domain.pkg
+                                    
+req.experienceId                    // The instance name of an app as a whole, where an app is mounted
+                                    // i.e. the 'example.com' part of https://example.com/foo
+                                    //      OR 'example.com#foo' if '/foo' is part of the app's mount point
+                                    
+req.clientApiUri                    // The api URL for the instance of an app
+                                    // the 'api.example.com' part of https://api.example.com/api/com.example.hello/kv/foo
+                                    
       req.pkgId             // the com.example.hello part of https://api.example.com/api/com.example.hello/kv/foo
 
       req.getSiteStore().then(function (models) {