Update API.md

API.md

@@ -176,33 +176,46 @@ req.clientApiUri                    // The api URL for the instance of an app
                                     
 req.pkgId                           // The name of the package being accessed
                                     // i.e. the 'hello@example.com' part of https://api.example.com/api/hello@example.com/kv/foo
+                                    
+req.oauth3.accountIdx               // The system id of the account represented by the token
+                                    // i.e. this is the user
 ```
 
 Internal (and/or deprecated) APIs that you will very likely encounter
 
 ```
-
 req.getSiteStore().then(function (models) {
   req.Models = models;
 });
 
-      req.Models.ComExampleHelloData.create(obj)
+//
+// Consider Models for a package 'hello@example.com', the would be named like so
+//
+req.Models.HelloExampleComData.create(obj)
 req.Models.ComExampleHelloData.save(obj)
 req.Models.ComExampleHelloData.find(params)
 req.Models.ComExampleHelloData.destroy(objOrId)
 
-      req.oauth3.accountIdx   // The system id of the account represented by the token
+//
+// These should be scoped in such a way that the only hand back data specific
+// to the experience and not expose secrets
+//
 
 req.getSiteConfig('com.example.hello').then(function (config) {
     // the com.example.hello section of /srv/walnut/etc/:domain/config.json
 });
 req.getSitePackageConfig
-      req.getSiteMailer().then(function (mailer) {});
 
-      // helper methods until we have agnostic means of doing the same / similar tasks
+//
+// Deprecated
+//
+// These helper methods should be moved to a capability
+
 req.Stripe
 req.Mandrill
 req.Mailchimp
+
+req.getSiteMailer().then(function (mailer) {});
 ```
 
 RESTful API Contstraints