From 56871bffd0a2634cc67c7cab402a6837fe0920c4 Mon Sep 17 00:00:00 2001
From: Bill Erickson <berickxx@gmail.com>
Date: Wed, 15 Apr 2015 11:59:20 -0400
Subject: [PATCH] web api preso cont.

Signed-off-by: Bill Erickson <berickxx@gmail.com>
---
 api_presentation/web_apis.asciidoc | 82 ++++++++++++++++++++++++++++++++------
 1 file changed, 70 insertions(+), 12 deletions(-)

diff --git a/api_presentation/web_apis.asciidoc b/api_presentation/web_apis.asciidoc
index a16e7eb90..945c866fc 100644
--- a/api_presentation/web_apis.asciidoc
+++ b/api_presentation/web_apis.asciidoc
@@ -10,7 +10,7 @@
 
 == Overview
 
- * IDL Basics
+ * IDL
  * PCRUD
   ** IDL Elements / Permissions
   ** Fleshing
@@ -22,16 +22,12 @@
   ** fieldmapper.standardRequest()
   ** egNet.request()
 
-
-== IDL
-////
-IDL is the DNA of Evergreen
-////
+== IDL : Evergreen DNA
 
 XML file which describes the structure of Evergreen classes.
 
  * Classes (e.g. user, copy, bib record, etc.)
- * Fields (e.g. user first name, user middle name, etc.)
+ * Fields (e.g. first name, middle name, etc.)
  * Relationships between classes
 
 == IDL Classes
@@ -40,9 +36,9 @@ XML file which describes the structure of Evergreen classes.
  * Virtual classes 
   ** Purely virtual for carrying data between application components
    *** E.g. "mvr" metabib virtual record
- ** Virtual classes whose content is defined by an SQL query.
-  *** oils_persist:readonly="true"
-  *** Effectively an inline database view
+  ** Virtual classes whose content is defined by an SQL query.
+   *** oils_persist:readonly="true"
+   *** Effectively an inline database view
 
 == IDL Virtual SQL-driven Class 
 
@@ -64,15 +60,77 @@ XML file which describes the structure of Evergreen classes.
             name="status" oils_persist:virtual="true" />
         <field reporter:label="Transit" 
             name="transit" oils_persist:virtual="true" />
-
 ---------------------------------------------------------------------------
 
 == Accessing the IDL
 
-file: /openils/conf/fm_IDL.xml
+ * Source file /openils/conf/fm_IDL.xml
+ * <script src="/IDL2js"></script>
+  ** 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
 
 == PCRUD
 
+ * Create, Retrieve, Update, Delete.
+ * Based on open-ils.cstore for speed.
+ * All actions are controlled by permission
+
+
+== PCRUD IDL Configuration
+
+ . What classes are accessible to PCRUD
+ . What actions on each class are permitted to PCRUD
+ . What permisssion(s) are required to perform each action
+ . What field to use as the context org unit for permission checks
+
+== PCRUD IDL Example
+[source,xml]
+---------------------------------------------------------------------------
+<permacrud xmlns="http://open-ils.org/spec/opensrf/IDL/permacrud/v1">  
+    <actions>                                                          
+        <create permission="CREATE_NON_CAT_TYPE" 
+            context_field="owning_lib"/>
+        <retrieve/>                                                    
+        <update permission="CREATE_NON_CAT_TYPE" 
+            context_field="owning_lib"/>
+        <delete permission="CREATE_NON_CAT_TYPE" 
+            context_field="owning_lib"/>
+    </actions>                                                         
+</permacrud> 
+---------------------------------------------------------------------------
+
+== PCRUD Permission Links and Jumps
+ * Check permission on linked object
+[source,xml]
+---------------------------------------------------------------------------
+<!-- fund_debit -->
+<retrieve permission="ADMIN_ACQ_FUND">                         
+    <context link="fund" field="org"/>                         
+</retrieve>                                                    
+---------------------------------------------------------------------------
+
+ * Check permission on linked object, 2 steps away
+[source,xml]
+---------------------------------------------------------------------------
+<!-- edi_message -->
+<retrieve permission="ADMIN_PROVIDER MANAGE_PROVIDER VIEW_PROVIDER">
+    <context link="account" jump="provider" field="owner"/>    
+</retrieve>        
+---------------------------------------------------------------------------
+
+== 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.
+
+
+
 ////
 warn against pcrud w/ too-complicated logic / too many calls
 build apis instead.
-- 
2.11.0