From fa552176e954677b1806c62cfe2297a7dd5c09db Mon Sep 17 00:00:00 2001 From: Bill Erickson Date: Mon, 11 May 2015 14:29:11 -0400 Subject: [PATCH] web api preso cont. Signed-off-by: Bill Erickson --- api_presentation/web_apis.asciidoc | 59 ++++++++++++++++++++++++-------------- 1 file changed, 37 insertions(+), 22 deletions(-) diff --git a/api_presentation/web_apis.asciidoc b/api_presentation/web_apis.asciidoc index d1c261eb2..96e976fbe 100644 --- a/api_presentation/web_apis.asciidoc +++ b/api_presentation/web_apis.asciidoc @@ -50,7 +50,8 @@ XML file which describes the structure of Evergreen classes. reporter:label="Organizational Unit" oils_persist:field_safe="true"> - + @@ -85,7 +86,7 @@ XML file which describes the structure of Evergreen classes. name="transit" oils_persist:virtual="true" /> --------------------------------------------------------------------------- -== Scripting (pre-browser client) +== Scripting (Dojo) [source,js] --------------------------------------------------------------------------- @@ -102,7 +103,7 @@ dojo.forEach(fieldmapper.IDL.classes.aou.fields, --------------------------------------------------------------------------- -== Scripting (browser client) +== Scripting (Angular) [source,js] --------------------------------------------------------------------------- @@ -118,6 +119,15 @@ angular.forEach(egCore.idl.classes.aou.fields, ); --------------------------------------------------------------------------- +== Perl + +[source,perl] +--------------------------------------------------------------------------- +use OpenILS::Utils::Fieldmapper; +my $org = new Fieldmapper::actor::org_unit(); +$org->name($name); +--------------------------------------------------------------------------- + == Accessing the IDL * Source file /openils/conf/fm_IDL.xml @@ -132,7 +142,7 @@ angular.forEach(egCore.idl.classes.aou.fields, [source,sh] --------------------------------------------------------------------------- -srfsh# request open-ils.pcrud open-ils.pcrud.retrieve.au "", 1 +srfsh# request open-ils.pcrud open-ils.pcrud.retrieve.aou "", 1 --------------------------------------------------------------------------- * Create, Retrieve, Update, Delete. @@ -142,10 +152,10 @@ srfsh# request open-ils.pcrud open-ils.pcrud.retrieve.au "", 1 == 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 + . Classes + . Actions + . Permissions + . Context org unit == PCRUD IDL Example [source,xml] @@ -209,7 +219,7 @@ srfsh# request open-ils.pcrud open-ils.pcrud.retrieve.au "", 1 srfsh# request open-ils.pcrud open-ils.pcrud.retrieve.aou "", 1 srfsh# request open-ils.pcrud open-ils.pcrud.search.aou - "", {"id":{"!=":null}} + "", {"ou_type":2,"id":{">":2}} srfsh# request open-ils.pcrud open-ils.pcrud.create.aou "", {"__c":"aou","__p":[null,"11","12","7","12",...]} @@ -285,7 +295,8 @@ Received Data: { == ANONYMOUS PCRUD * Access to public data for unauthenticated clients - * Slight speed bump by avoiding open-ils.auth call and perm checks + * Improves speed by avoiding open-ils.auth call and perm checks + * Read-only [source,xml] --------------------------------------------------------------------------- @@ -297,7 +308,7 @@ Received Data: { srfsh# request open-ils.pcrud open-ils.pcrud.retrieve.aou "ANONYMOUS", 1 --------------------------------------------------------------------------- -== PCRUD JavaScript Interface (pre-browser client) +== PCRUD JavaScript Interface (Dojo) [source,js] --------------------------------------------------------------------------- @@ -307,15 +318,22 @@ pcrud.retrieve('aou', 1, {oncomplete : function(org) { ... }}); pcrud.update(some_org, {oncomplete : function(resp) { ... }}); pcrud.search('aou', {parent_ou : 1}, { - oncomplete : function(r) { - var orgs = openils.Util.readResponse(r); - console.log('org units: ' + orgs); + oncomplete : function() {...}, + onerror : function() {...}, + onresponse : function(r) { // streams in XUL client only + var org = openils.Util.readResponse(r); + console.log('one org unit: ' + org); } }); --------------------------------------------------------------------------- -== PCRUD JavaScript Interface (browser client) +== A Quick Note on Promises + + * Read this: https://docs.angularjs.org/api/ng/service/$q + * See also: http://yeti.esilibrary.com/dev/pub/web-staff-log.html#_2013_12_04_promises_in_angularjs + +== PCRUD JavaScript Interface (Angular) * Uses promises * Defaults to streaming searches @@ -329,7 +347,7 @@ egCore.pcrud.search('aou', {parent_ou : 1}) .then( function() {...}, // oncomplete function() {...}, // onerror - function(one_org) { // onresponse + function(one_org) { // onresponse -- streams universally supported console.log('one org unit: ' + one_org); } }); @@ -337,12 +355,9 @@ egCore.pcrud.search('aou', {parent_ou : 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. + * PCRUD is powerful and fast, but it's not a replacement for an API. + * Be wary of large amounts of data traversing the network + * Avoid sequestering re-usable code in a client application. == Fielder -- 2.11.0