Forum OpenACS Development: JSON Endpoint documentation

Request notifications

Collapse
Posted by Malte Sussdorff on
I am looking for a better practice than what we are using with regards to our JSON endpoints for the Apps we are building on top of ]project-open[.

Goal: Enforce proper documentation for endpoints, so you don't have to look at the code to find out the JSON structure returned.

Current Solution:
- using ad_proc with multiple @return (similar to @param), supported in proc_view (so it actually displays all the @return) for a single object (and you might return multiple of those)
- im_json_return_object procedure which builds a JSON object based on the documentation (looking at the documentation, looking at the calling environments variables and then piecing the elements together).

It helps us at the moment to ensure that the documentation of the endpoint procedures (and there is logic in intranet-rest to turn a "normal" procedure into an endpoint) is written and kept up to date.

BUT.... We defer types from variable naming (e.g. _p is most likely a boolean, so we transfer 0/1 etc. into "false/true" ; _id is an id, so return it as a number). And it doesn't work with nested objects.

As we are getting non TCL developers into the company, who "just" need to use the endpoints, I was wondering how others are treating the documentation solution and what you found as best practices. I was considering createing something like "im_rest_proc" or "im_rest_endpoint_proc" which could add the ability to generate swagger.io based documentation, getting rid of the changes we made to acs-core "ad_proc" (and the proc-view only documentation). Stumbling across rl_json, I also considered using their template style to use for the documentation building etc.

But... long story short, before I venture off on my own, maybe you have some pointers how to best achieve the goal of providing Endpoint documentation from within the TCL code for non TCL developers.