[
https://issues.apache.org/jira/browse/JSPWIKI-1310?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18133507#comment-18133507
]
Arturo Bernal commented on JSPWIKI-1310:
----------------------------------------
I attached a draft of the OpenAPI description for a first version
(jspwiki-api-v1-draft.yaml). It covers only read operations: search, page name
suggestions and the list of plugins. Nothing is implemented.
It describes the target, not what the /ajax/ services do today. The header of
the file lists the differences. I would like opinions on three choices before
any code is written:
Base path: new endpoints under /api/v1, instead of reusing /ajax/.
Parameters: ordinary query parameters (query and max) instead of the single
comma separated params used today.
Errors: real 401, 403 and 400 answers with a JSON body, instead of the 400 with
an HTML page that every failure gets today.
If nobody objects, the next step is one endpoint (search) with a test that
compares the description with the real responses.
> 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
> Attachments: jspwiki-api-v1-draft.yaml
>
>
> 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)
