Forum OpenACS Development: API Browser Support for Other Programming Languages

Dear all,
in a way the title says it all.

Supposing I would like to add to the API Browser (or Xowiki) the capability of processing sources written in another language, not TCL and supposing I have external lexers/parsers able to extract all information that is needed by the API Browser (or Xowiki), wich way would you go to implement this functionality?

Do you think it would be feasible?

Thanks in advance,

Posted by Gustaf Neumann on
The API browser does not have to do much with xowiki. The API is providing a general interface, which is programming language agnostic [1].

In essence, the information is kept in an nsv, which can be filled with data from different providers. To explore what is the content of this data structure e.g. for the function "acs_user::get_by_username", use the following from ds/shell:

nsv_dict keys api_proc_doc acs_user::get_by_username

The command "ns_dict" was introduced recently in NaviServer, for older version, one can use:

dict keys [nsv_get api_proc_doc acs_user::get_by_username]

To get a certain dict entry, use

nsv_dict get api_proc_doc  acs_user::get_by_username main

Pretty-printing of the source-code is performed through [2] based on the proc-name and introspection, so this will need some awareness of other languages (by e.g. adding as well a language identifier to the dict, etc.), but here the question arises, how much information will be provided. Currently, the API-browsers provides minimal support for e.g. SQL [3] (also XQL [3]), but it does not show the used .css files (there is just minimal support via the developer support, but often the CSS and/or JavaScript files are minified and nor really useful).

So, depending on the goals, one can go different direction, it really depends, what other languages one has in mind...

Hope this helps


Posted by Carl Lemp on
I have a couple of other questions related to this topic if someone could be so kind to share their expertise.

If I want to treat source code as content (code-content) and allow users to leverage the features of the apm and api-browser to import and explore this code-content using OpenACS, is there a way to restrict the scope of the api-browser to only certain packages? To use these tools for this purpose, it would be better if the user only had access to the imported code-content but not be exposed to the the normal code-packages that make up the OpenACS site. Is that possible within a single site?

I noticed that when setting up a sub-site, the api-browser was not an application that can be installed in a sub-site so I assume it's scope is site-wide. Is there any way to restrict that?

Thanks in advance,

Posted by Iuri Sampaio on
If I understood correctly you need, the best way to inhibit api-browser from the user is to work properly with permission system.
Site-wide-administration, SWA, is designed to own (i.e. have access) the entire system, to access api-browser, developer support tools, and a bunch of other features. You don't want to change that. Believe me!

A Subsite administrator is the one you should be setting up to be your admin for site administration tasks.

Could you create a custom package for that?
A possibility is to make it available to site admins, then they won’t have access to the api-browser section, but they will have access to your "custom code library" package.

Best wishes

Posted by Carl Lemp on
What I would like to do is allow the user to use the api-browser but only them to browse packages they loaded, not packages that are part of the base system.

If I understand your answer correctly, the api-browser has site-wide-administration permissions and it is bad idea to change those permissions. So, to do what I want, the best way would be to create a separate package with the same capabilities (maybe starting with the same code?) as the api-browser and set the permissions of that package as I need them. Is that correct?


Posted by Gustaf Neumann on
Actually, i do not see the big problem in changing permissions of the api-browser.

The api-browser was designed and implemented as a singleton package for providing documentation for developers about the code running on this instance (there is only one code basis). If one wants multiple instances to be used for different purposes, maybe in multiple subsites, one has to
- remove the singleton-property (with all consequences),
- make the package subsite-aware (maybe not much),
- provide configuration options per instance (what kind of code you want to see),
- extend the API in what instance the data should be seen (and maybe provide as well source-code language information)
- extend the data-model (i.e. the nsvs, naming etc.)

This is some effort, but it it look in general doable to me, since the existing API and datastructures are rather simple. One should be able to provide default settings, such that existing usages can continue to work unmodified.

Posted by Jim Lynch on
Hi, are there other programming languages that can be used in openacs, with the same connections to naviserv as TCL?


Regarding client side languages: HTML5, CSS and Javascript;
and Server side: In the past AOLServer supported PHP
From what i understood from Carl is that he has an application in mind, where one can use the API-Browser to manage/browser/navigate through a code-base that does not have to be executed in the OpenACS environment. That code to be managed might be implemented in arbitrary programming languages.

Concerning the languages that are executed within NaviServer/OpenACS environment. Aside of the fact, that nsf can be used for defining multiple languages (including domain specific languages), there is e.g. support for PHP (since 4.99.19 PHP 7.3.5, Stefan did the enrollment module in PHP for canceled OpenACS conference last year), and there is an ocaml module for NaviServer, etc.. Last but not least, the full code basis of Tcl/NaviServer is in C, most modules/packages are implemented in C.. why not including these in browser? On the server-side we have as well SQL. And then, we have the client-side languages, with java-script, CSS, etc.)

Yes, I've been looking into leveraging the code exploration features already built for OpenACS in the API browser but as I look at OpenACS more, I am also evaluating if XOWiki is a better path for the same purpose. The source code for the target system could be converted to cross referenced HTML pages through an external tool and then those pages could be imported into XOWiki where metadata and additional links can be added.


This sound certainly doable.

Some of the features will be different (call graph, test-coverage, ...) ... but depending on the generator tool, it might be even better.

I have been wondering lately, as I already have an „ad_proc to OpenAPI“ converter, to go the other way around to generate the server code based of an OpenAPI specification. Main reason is to get into an API First development approach, which is driven by the specification and not by ad_proc documentation block (though the latter part works, it‘s just, well,... not what others do 😉).

This being said, we could (in the same route) actually use the OpenAPI Specification to create ad_procs for REMOTE functions, allowing you to call extended functionality with procedures available in the API Browser. Then you are not only language independent but also independent of the Webbrowser.

=> „Microservice to the rescue“ (*cough* ..... not to be taken seriously, < /sarcasm>).

What do others think of this approach (turn OpenAPI.yml into ad_procs during parse time) - would this be of interest? And would be do this on run time (so we could reload the OpenAPI.yml to dynamically add procs) or just to parse and create „static“ generated-from-OpenAPI-procs.tcl files