Forum OpenACS Development: Exposing all of OpenACS/]po[ via REST

Summary:

We are close to finishing an industry strength yet simple REST Web-Service interface that exposes most of OpenACS/]po[. The code is available under the GPL V2 or higher at:
cvs -d :pserver:mailto:anonymous@cvs.project-open.net:/home/cvsroot checkout intranet-rest
We are posting this information because we would like to receive feedback on the structure of the REST interface.

Here is the Story:

For a recently acquired customer we have to create a Web services that exposes _all_ of OpenACS/]project-open[ to 3rd party (M$-) applications via a Web service.

Fortunately, the customer is pretty neutral with respect to the type of Web-Service used. Going the REST way, I believe we are - finally - getting closer to a truly universal Web-Service that fulfills the dream of:

- Being simple to understand, use and maintain
- Cover all important areas of OpenACS/]po[

Looking at Twist and XoSOAP in the past months, I just didn't get a good feeling. XoSOAP seems to be quite advanced, but probably too complex for 98% of all developers in this world. Considering that more then 10 different applications will have to access the Web-Service, we need something simple, robust, maintainable and interoperable with the Microsoft world.

So in the last weeks we have put together an advanced prototype of a REST-based Web-Service that exposes basically all OpenACS/]project-open[ objects.

The basic idea of this "intranet-rest" service is to use existing meta-information from acs_object_types and acs_object_type_tables to implement generic "CRUL" operations:

- R=Read: Return all fields of an object by going through the object's database tables and their columns. Just map database columns and their values to XML tags.
- U=Update: Update the object's database columns in the same way as R=Read.
- L=List: List the objects for a given object type, allowing the user to pass a security-checked WHERE-query via the URL.
- C=Create: We have decided to use custom TCL procedures per object type to handle object creation. That seems OK, because our customer's applications actually need to "create" only few object types.

Please see http://www.project-open.org/documentation/download/file/PO-Dev-REST-Interface.091218c.ppt for a detailed design document.

The advanced prototype is already running in the Internet. Please go to http://po34demo.project-open.net/, login as "Ben Bigboss" and then enter the URL /intranet-rest. The "HTML mode" will allow you to browse and explore the REST resources interactively. For XML access just try a query like this one:

wget -O - --user=bbigboss@tigerpond.com --password=ben --auth-no-challenge http://po34demo.project-open.net/intranet-rest/im_project/16030

As I said: We would be very interested to receive feedback.

Cheers!
Frank

Thanks for your comment. Sorry, our demo server reset-procedure has overwritten the intranet-rest installation. I've introduced intranet-rest now in our "demo-master" and I've checked the access, it's working now:

wget -O - --user=bbigboss@tigerpond.com --password=ben http://po34demo.project-open.net/intranet-rest/im_project

Cheers!
Frank

I used SOAP based web services in the past, but if there is no a specific customer requirement, the REST way is sooooooo easy!

Sorry, you are right, you found a dependency on the ]po[ "intranet-core" package. However, there are not many of them, and they are very basic and not at the core of the REST interface. The dependencies are mostly permission checks that allow a ]po[ admin to configure user permissions to the various object types:

- im_valid_auto_login_p: Just create a stub that returns "1". For details please check intranet-core/tc/intranet-defs-procs.tcl, the procedure tests if a "auto-login token" is a valid hash of the user's password...

- im_security_alert_check_integer: Just create a stub that does nothing. The procedure performs a security check if the argument is an integer or a list of integers.

- im_header, im_footer and im_navbar: Please replace with ad_header and ad_footer or similar...

- im_object_permission: Please create a stub returning 1.

- im_permission: Please create a stub returning 1.

- im_url_with_query: Replace with "[ad_conn url]?[ad_conn form]" or similar

- im_is_user_site_wide_or_intranet_admin: Please create a stub returning 1.

- The package references a few ]po[ object types and branches into custom treatment for these types (im_categories and im_invoice_items). You can just remove these.

- The /www/index.tcl file references im_object_permission_p, which you can replace by a stub returning 1

- The intranet-rest-create.sql file will try to update a few metadata fields in acs_object_types which are extensions for ]po[, you can safely ignore them. You can also ignore any issue related to the fields im_rest_object_type.object_type_status_id and object_type_type_id and its catagories. These fields are not used, you should remove the not null and the RI constraints from the database table definition.

Cheers!
Frank

I am interested in the implementation of permissions

Then I would recommend you to download the file project-open-Update-3.4.0.8.0b.tgz from https://sourceforge.net/projects/project-open/files/, remove all duplicate packages and install the intranet-* packages. That should just work on top of a standard OpenACS 5.3 or 5.4 installation, at least we've successfully tested it a year ago.

Or just download one of the ]po[ installers from that Web site and install intranet-rest.

In about an hour I'll be available on Skype:frankxbergmann if you need help. I'd be happy to explain you about ]po[ "application permissions", which are based on the OpenACS permission system, but which contain application specific business logic.

Cheers!
Frank