web api preso cont.

Signed-off-by: Bill Erickson <berickxx@gmail.com>

diff --git a/api_presentation/web_apis.asciidoc b/api_presentation/web_apis.asciidoc
index 945c866..c5a890a 100644 (file)
--- a/api_presentation/web_apis.asciidoc
+++ b/api_presentation/web_apis.asciidoc
@@ -69,11 +69,16 @@ XML file which describes the structure of Evergreen classes.
   ** Exports a JS object
  * http://example.org/IDL2js?locale=fr-CA
  * http://example.org/IDL2js?locale=fr-CA&au,ahr,acp
- * http://example/reports/fm_IDL.xml?locale=fr-CA
- * http://192.168.122.123/reports/fm_IDL.xml?class=au&class=ahr
+ * http://example.org/reports/fm_IDL.xml?locale=fr-CA
+ * http://example.org/reports/fm_IDL.xml?class=au&class=ahr
 
 == PCRUD
 
+[source,sh]
+---------------------------------------------------------------------------
+srfsh# request open-ils.pcrud open-ils.pcrud.retrieve.au "<auth>", 1
+---------------------------------------------------------------------------
+
  * Create, Retrieve, Update, Delete.
  * Based on open-ils.cstore for speed.
  * All actions are controlled by permission
@@ -123,18 +128,96 @@ XML file which describes the structure of Evergreen classes.
 
 == PCRUD-related IDL Attributes
 
- * controller="open-ils.cstore open-ils.pcrud"
- * ignore_object_perms="true"
-  ** Skip all object-specific permission checks (for speed)
- * global_required="true"
-  ** There is no context org unit; permission must be global.
+ * Give PCRUD access to the class
+
+[source,xml]
+---------------------------------------------------------------------------
+<class id="vmp" controller="open-ils.cstore open-ils.pcrud" ...
+---------------------------------------------------------------------------
+ * Avoid object-specific permission checks
+[source,xml]
+---------------------------------------------------------------------------
+<permacrud xmlns="http://open-ils.org/spec/opensrf/IDL/permacrud/v1" 
+    ignore_object_perms="true">
+---------------------------------------------------------------------------
+ * Require global permissions
+[source,xml]
+---------------------------------------------------------------------------
+<create permission="ADMIN_FLOAT_GROUPS" global_required="true"/>
+---------------------------------------------------------------------------
+
+== Fleshing, Sorting, Limiting
+
+ * Fleshing
+
+[source,sh]
+---------------------------------------------------------------------------
+srfsh# request open-ils.pcrud open-ils.pcrud.retrieve.au "<auth>", 1, 
+    {"flesh":2,"flesh_fields":{"au":["home_ou"],"aou":["ou_type"]}}
+---------------------------------------------------------------------------
+
+ * Sorting, Limiting
+
+[source,sh]
+---------------------------------------------------------------------------
+srfsh# request open-ils.pcrud open-ils.pcrud.search.aou "<auth>", 
+    {"id":{"!=":null}}, {"order_by":{"aou":"name desc"}, "limit":3}
+---------------------------------------------------------------------------
+
+ * Sorting multiple fields
+[source,sh]
+---------------------------------------------------------------------------
+srfsh# request open-ils.pcrud open-ils.pcrud.search.aou "<auth>", 
+    {"id":{"!=":null}}, 
+    {"order_by":[
+        {"class" : "aou", "field" : "parent_ou"}, 
+        {"class" : "aou", "field" : "name", "direction" : "desc"}
+    ]}
+---------------------------------------------------------------------------
+
+== Selecting
+
+[source,sh]
+---------------------------------------------------------------------------
+srfsh# request open-ils.pcrud open-ils.pcrud.retrieve.bre "<auth>", 1, 
+    {"select":{"bre":[
+    "id","create_date","editor","tcn_value","fingerprint"]}}
+
+Received Data: {
+  "__c":"bre",
+  "__p":[
+    null,
+    null,
+    null,
+    "2015-04-24T11:26:11-0400",
+    null,
+    null,
+    null,
+    1,
+    "lacanzoneitalianadelnovecentobaldazzi",
+    1,
+    null,
+    null,
+    null,
+    null,
+    null,
+    "1"
+  ]
+}
+---------------------------------------------------------------------------
+
+
+== When Not To Use PCRUD
 
+ * PCRUD is powerful enough to implement most logic in the client, but 
+   it's not always the best choice.
+ * Avoid putting complex logic in client code (e.g. web code) which 
+   may be needed by other client code.  Use the API.  
+ * With web development in particular, sufficiently complex logic will
+   be faster as an API call, since less data has to traverse the network.
 
+== API Call Structure
 
-////
-warn against pcrud w/ too-complicated logic / too many calls
-build apis instead.
-////
 
 == Questions / Comments