From 9fc0436bf24bb44718ef9af0b9b6750726eb2d46 Mon Sep 17 00:00:00 2001
From: AJ ONeal <aj@daplie.com>
Date: Wed, 2 Aug 2017 18:28:41 -0600
Subject: [PATCH] Update API.md

---
 API.md | 47 ++++++++++++++++++++++++++++++-----------------
 1 file changed, 30 insertions(+), 17 deletions(-)

diff --git a/API.md b/API.md
index 8843110..7160178 100644
--- a/API.md
+++ b/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.getSiteStore().then(function (models) {
-        req.Models = models;
-      });
+//
+// 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.Models.ComExampleHelloData.create(obj)
-      req.Models.ComExampleHelloData.save(obj)
-      req.Models.ComExampleHelloData.find(params)
-      req.Models.ComExampleHelloData.destroy(objOrId)
+//
+// These should be scoped in such a way that the only hand back data specific
+// to the experience and not expose secrets
+//
 
-      req.oauth3.accountIdx   // The system id of the account represented by the token
+req.getSiteConfig('com.example.hello').then(function (config) {
+    // the com.example.hello section of /srv/walnut/etc/:domain/config.json
+});
+req.getSitePackageConfig
 
-      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) {});
+//
+// Deprecated
+//
+// These helper methods should be moved to a capability
 
-      // helper methods until we have agnostic means of doing the same / similar tasks
-      req.Stripe
-      req.Mandrill
-      req.Mailchimp
+req.Stripe
+req.Mandrill
+req.Mailchimp
+
+req.getSiteMailer().then(function (mailer) {});
 ```
 
 RESTful API Contstraints