[
https://issues.apache.org/jira/browse/JSPWIKI-1310?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18133506#comment-18133506
]
Arturo Bernal commented on JSPWIKI-1310:
----------------------------------------
Measurements of the endpoints on a running instance (Tomcat 10.1 with a war
built from master plus an unrelated parser change, anonymous session). They are
the baseline for the first version of the contract.
Correction to the description: the servlet mappings for /atom/* and for XML-RPC
(/RPC2/, /RPCU/) are commented out in web.xml, so both return 404 by default,
not only XML-RPC. /rss.jsp also returned 404 in this setup. I have not checked
why.
Ajax services, active by default:
GET /ajax/search/pages?params=text,max returns 200 with a JSON list of objects
with the fields score and page.
GET /ajax/search/suggestions?params=text,max returns 200 with a JSON list of
page names.
GET /ajax/plugins/plugins returns 200 with a JSON list of objects with
displayName and snip. It is the only service that works without the CSRF token.
GET /ajax/progressTracker?params=id returns 200 with an empty body and no
content type for an unknown id.
The users service needs AllPermission and is not usable by anonymous callers.
Behaviour a contract has to settle:
A missing token, an unknown service and a denied permission all return 400 with
an HTML error page. There is no 401, 403 or 404, so a client cannot tell them
apart.
A search without params returns 200 with an empty body, and an unknown action
returns 200 with an empty list.
The token is accepted as a header or as a query parameter. On a POST,
CsrfProtectionFilter only accepts it as a request parameter: a POST to a search
service with the header alone was redirected with 302 to /error/Forbidden.html.
Proposal for the first version: describe the read operations (search,
suggestions, plugins) with real 401, 403 and 404 responses, and leave write
operations, API tokens and the migration of the JSPs for a second phase. I will
write the OpenAPI description for that scope next.
> 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)
