Forum OpenACS Development: Generic REST API for OpenACS / ]project-open[ HTML5 Pages

Hi Guys,

There are some discussion in another thread about "support" for "modern GUIs". So I just wanted to present the generic REST interface that we have developed in ]project-open[ during the last ~5 years or so.

http://www.project-open.com/en/package-intranet-rest

Features

- Full CRUD + L support: Create, Read, Update, Delete objects, plus "L"=List objects based on properties or a safe subset of SQL for filtering.
- It exposes _all_ OpenACS object types to Web in a generic way. Only creation and deletion of object types requires some manual coding because of the PlPg/SQL procedures to be called. But that's about 10-20 lines per object type.
- It includes dependencies to the ]po[ "DynField" infrastructure and has custom ]po[ permission checks, but it would be easy to remove these dependencies to create a pure OpenACS REST interface

Examples


We have developed all recent HTML5 functionality in ]po[ using this API. Just to to the ]po[ demo server, login as Ben Bigboss and have a look at any project of type "Gantt Project":
https://demo.project-open.net/

Examples include:
- Gantt Editor (Microsoft Project): http://www.project-open.com/en/package-intranet-gantt-editor
- Loads of diagrams and indicators
- Hour logging with per-minute precision
- ...

Limits


There are some limits for the generic part. For example, some of our widgets need tree structures (project tasks and sub-tasks, cost centers and sub-centers, budget items and sub-items), which isn't supported in the generic REST API. Also, there are some very performance critical cases, where we had to develop manually optimized SQLs. But we cover 80-90% of all back-end functionality using this interface.

GraphQL vs. ]po[ REST


We've developed our REST API before the appearance of GraphQL. I like GraphQL a lot, and with this information the ]po[ REST would have looked a lot more like it than it currently does.

It's funny (but logical) that both APIs address similar issues:
- De-referenced information - Not only send object_id's, but also the name of the object and additional information.
- Performance - only send information you really need, but not more
- Permissions

At the end, the ]po[ REST API is actually a REST API, but GraphQL is not. I've heard the first critical voiced about that recently.

Also the ]po[ REST API allows to update and create objects with the same level of support as reading object information. I understand GraphQL is not that good at write operations.

Availability


The REST API is currently licensed under our "free license". But we offer everybody to use this code without the ]po[ dependencies under a "GPL V2 or higher" license.

Future Development


Integrating application-level permissions in a REST API is not easy. We've found a workable solution, but it's not particularly elegant. Maybe there are better ideas coming from you?

You can have a look at the source code here:

http://www.project-open.com/en/package-intranet-rest
(scroll down for the "Package Documentation" section).

acs-object-management provides an API to manage object types, including in-table and extension table definition of attributes, forms, and a Tcl API to the database pl/sql layer.

It might be a good place to start.

I also just discovered this Python library that provides a really good API to serialize objects to and from JSON that makes no assumptions about how the data is used. It may provide inspiration.

https://marshmallow.readthedocs.io/en/stable/why.html