Forum OpenACS Q&A: providing RESTful apis

Request notifications

Collapse
Posted by Jeff Rogers on
I'm looking at providing an api to my application. There already exists the xml-rpc server and it has a nice clean interface to let packages register their own apis there. But xml-rpc feels a bit antiquated and a little more complicated to deal with than a simple REST api (using the term loosely; basically meaning a simple url GET with query parameters).

Is there anything I've missed for providing this kind of service? If it's not already there, is there any interest other than mine? It's not difficult to provide this sort of thing as one-off behavior, but it would be nice to have a general way to do it that handles things like managing API keys, handling input in plain xml or json format, and similarly encoding the results.

Collapse
2: Re: providing RESTful apis (response to 1)
Posted by Brian Fenton on
Hi Jeff

I know Frank Bergmann did some work around this for Project Open. It could be worth searching for some of his posts here.

best wishes
Brian

Collapse
3: Re: providing RESTful apis (response to 1)
Posted by Dave Bauer on
Seems like it is a good idea.

Don added json-procs.tcl to acs-tcl package last August, very handy.

http://cvs.openacs.org/browse/OpenACS/openacs-4/packages/acs-tcl/tcl/json-procs.tcl

Basically you need an API to register procs that can return a datasource you can convert to/from JSON.

In general, I find you still need to end up writing specific procedures since very few applications use simple objects, although maybe with acs-object-management you could manage different views and provide those with JSON.

Collapse
4: Re: providing RESTful apis (response to 3)
Posted by Dave Bauer on
If you look at acs-object-management it gives you the tools to build up views/forms based on object types that would be useful to develop the data structures used in an restful API.
Collapse
5: Re: providing RESTful apis (response to 1)
Posted by Brian Fenton on
So, it's 2019, and I'm wondering if there is any change in the situation regarding RESTful APIs? For example, I have been asked to look into integrating with a digital signature product https://developers.docusign.com/esign-rest-api/guides/requests-and-responses and I'm wondering if there is anything in more recent OpenACS that may help?

Brian

Collapse
6: Re: providing RESTful apis (response to 1)
Posted by Antonio Pisano on
Dear Brian,

OpenACS versions older than this forum thread have indeed some more features that will help when interfacing with web apis:
- a more complete and performant HTTP client interface ([1][2][3])
- tDOM Json support [4]

I would personally not make it any more complicated than this, unless SOAP or similar friends were a requirement.

I cannot really comment on current status of xml-rpc package

Ciao

[1] https://openacs.org/api-doc/proc-view?proc=util::http::get&source_p=1
[2] https://openacs.org/api-doc/proc-view?proc=util::http::post&source_p=1
[3] https://naviserver.sourceforge.io/n/naviserver/files/ns_http.html
[4] http://www.tdom.org/index.html/doc/trunk/doc/dom.html

Collapse
7: Re: providing RESTful apis (response to 1)
Posted by Brian Fenton on
Ciao Antonio

thanks for this advice! Just wondering is there any reason you would recommend TDOM for JSON instead of the json-procs.tcl that Dave mentioned above? http://cvs.openacs.org/browse/OpenACS/openacs-4/packages/acs-tcl/tcl/json-procs.tcl

Brian

Collapse
8: Re: providing RESTful apis (response to 1)
Posted by Antonio Pisano on
Personally, I would prefer tDOM nowadays as it provides an efficient parser, with a standardized object representation which makes it easy e.g. to convert JSON to XML and vice-versa. This makes also the code less OpenACS-specific.

What might be sometimes harder with tDOM is coping with broken markup or json: even if options are there to mitigate this, tDOM will just not swallow everything you throw at it. In this cases, some hamfisted string parsing does the trick, for me at least. Not sure how tolerant the json-procs are.

In the end, to me there is nothing wrong with the json-procs if they float your boat, is a matter of taste :-)

Ciao

Collapse
9: Re: providing RESTful apis (response to 1)
Posted by Brian Fenton on
Thanks Antonio!

I have actually used the json-procs.tcl recently to generate JSON, and once you get them working they are good, but I found them a little unintuitive at first.

saluti
Brian

Collapse
Posted by Frank Bergmann on
Hi!

Please have a quick look at our REST documentation:
http://www.project-open.net/en/package-intranet-rest

The ]po[ REST interface is completely generic.

I have checked, there is one dependency with a ]po[ specific functionality "DynFields" functionality used for "dereferencing" fields which you can ignore, and there are ]po[ specific permission checks in a number of places which you can replace with your own.

You can publish such a modified version using any license you prefer.

Cheers
Frank