[
https://issues.apache.org/jira/browse/JSPWIKI-1310?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18132777#comment-18132777
]
Arturo Bernal commented on JSPWIKI-1310:
----------------------------------------
Inventory of the endpoints that exist today, taken from the code and from the
web.xml of jspwiki-war, after the discussion on
[[email protected]|mailto:[email protected]] on 27 October. Alex
O'Ree pointed out that the operations are spread over servlets, JSP pages and
the Ajax services, that unifying them would be a very large change, and that a
hand written OpenAPI description of what exists could be a lighter first step
than adding a REST library.
Servlets that are mapped by default: WikiAjaxDispatcherServlet on /ajax/,
WikiServlet on /wiki/ and AttachmentServlet on /attach/. The Atom servlet is
declared, but its mapping on /atom/ is commented out and disabled by default.
The class RPCServlet exists in the jspwiki-xmlrpc module, but this web.xml does
not declare an RPC servlet; /RPC2/ and /RPCU/ only appear as URL patterns in
another block and in comments. I have not checked how XML-RPC is enabled.
JSP pages in the root of the web application, 27 of them: Comment, CookieError,
DeleteGroup, Delete, Diff, EditGroup, Edit, Error, Group, Install, LoginForm,
Login, Logout, LostPassword, Message, NewBlogEntry, NewGroup, PageInfo,
PageModified, Preview, Rename, rss, Search, SisterSites, Upload,
UserPreferences, Wiki, Workflow and XHRHtml2Markup. Several write operations
(delete, rename, upload, create a group) go through these pages, which answer
with HTML and redirects and not with JSON.
Ajax services registered on /ajax/: progressTracker (DefaultProgressManager),
search and plugins (DefaultSearchManager), users (DefaultUserManager) and
SampleAjaxPlugin, which is an example. A plugin that implements WikiAjaxServlet
is registered by DefaultPluginManager. The dispatcher passes an action name and
a list of comma separated parameters to the service.
Not checked yet: what each Ajax service returns, and which permission each one
requires. That would be needed before writing any description.
> Add a versioned REST API with an OpenAPI description
> ----------------------------------------------------
>
> Key: JSPWIKI-1310
> URL: https://issues.apache.org/jira/browse/JSPWIKI-1310
> Project: JSPWiki
> Issue Type: New Feature
> Reporter: Arturo Bernal
> Priority: Major
>
> JSPWiki has no documented REST API. What exists today is the following.
>
> The servlet at /ajax/ (WikiAjaxDispatcherServlet), where the managers
> register JSON endpoints for the web user interface: users, search, the
> progress tracker and the ones that plugins define. They are made for the UI,
> are not documented and make no promise of stability.
>
> XML-RPC (/RPC2/ and /RPCU/), which web.xml has commented out by default, and
> the Atom API (/atom/).
>
> The build has no JAX-RS, OpenAPI or similar dependency.
>
> Proposal: a versioned REST API that speaks JSON and is described with
> OpenAPI, so that integrations, bots and other front ends do not have to
> depend on the ajax endpoints of the UI or on XML-RPC.
>
> Things to settle before writing code, which should be discussed on
> [[email protected]|mailto:[email protected]] first:
> the scope of a first version (read operations on pages, versions, attachment
> metadata, search and referrers; write operations later);
> how callers authenticate (the wiki session with its CSRF token, API tokens,
> or the container) and how permissions are enforced, which should be the same
> AuthorizationManager and ACLs as in the UI;
> the technology (a Jakarta REST implementation or plain servlets) and where
> the code lives (a new module?), on Java 17;
> what happens to the XML-RPC and Atom APIs (kept, deprecated);
> how the OpenAPI description is produced (from annotations or written by hand)
> and published.
>
> This ticket is only the proposal; there is no implementation.
--
This message was sent by Atlassian Jira
(v10.3.26#10030026)
