Skip to content

JSPWIKI-1310 Add the search of the REST API version 1 - #589

Open
arturobernalg wants to merge 9 commits into
apache:masterfrom
arturobernalg:feature/JSPWIKI-1310-search
Open

arturobernalg wants to merge 9 commits into
apache:masterfrom
arturobernalg:feature/JSPWIKI-1310-search

Conversation

@arturobernalg

Copy link
Copy Markdown
Member

First step of https://issues.apache.org/jira/browse/JSPWIKI-1310, following the discussion on dev@. It adds GET /api/v1/search, with the query parameters query and max and JSON answers, described by a hand written OpenAPI file (openapi.yaml in org.apache.wiki.rest). It is registered in web.xml as ApiV1Servlet on /api/v1/*, and adds no runtime dependency.

An anonymous caller without permission gets 401 and a logged in one gets 403. A missing query, a max that is not a positive integer and a query Lucene cannot parse are 400. Before the Lucene index exists, which is the first minute after the start, the answer is 503: LuceneSearchProvider.findPages logs the failure and returns null, and the servlet handles that. To tell the broken query apart, ProviderException has a constructor with a cause now, and the Lucene provider keeps the ParseException as the cause.

A test compares the status, the content type and the shape of the body of each answer with openapi.yaml. It reads the file with snakeyaml, a new dependency with test scope only.

Checked locally: jspwiki-main 1048 tests pass, 11 of them new; and on a running war (Tomcat 10.1) with two indexed pages, the results, max, an empty result, 400 and 503. Not tested: login, logout and /pages/{page}, which are not implemented yet, and the integration tests.

One open point: the permission checked is view on all pages, as in /ajax/. With a policy that grants view only on some pages, those users get 401 or 403 even if they can see some pages. The ChangeLog entry comes in a separate commit with the number of this pull request.

@spyhunter99

Copy link
Copy Markdown
Contributor

i think this looks good however i think further features should be pushed to 3.1

@arturobernalg

Copy link
Copy Markdown
Member Author

Thanks. I agree that the rest waits for 3.1: this pull request is only the search of the REST API version 1, and the page name suggestions and the list of plugins are in #590, which can wait. If this one looks good to you, could you merge it?

@juanpablo-santos

Copy link
Copy Markdown
Contributor

Hi! Some comments, regardless when this comes in

  • separate module: wouldn't these classes fit better on a separate maven module? jspwiki-rest-api or whatever name we came up with
  • gson vs Jackson: both are in classpath, but I don't know if we're using one or both, should use one. Perhaps better suited for another PR?
  • endorsed lib: an endorsed lib inside web-inf allows to put APIs not included by tomcat as if tomcat itself would bundle it. JAX-RS could be placed that way, would that be useful?
  • openapi-generator: don't have in mind if It covers plain java to derive from the contract, but may be worth to look into

WDYT? Anyway, thanks for the PR! IMO, very much needed :-)

@arturobernalg

Copy link
Copy Markdown
Member Author

Thanks, JP. A separate module sounds right, and it was an open question in the ticket; I would do it in a follow-up pull request, so this one stays small. About the JSON library: this servlet uses Gson, like AjaxUtil, but Jackson is also in use in the project (ProductUpdateChecker and DefaultUserManager), so the project should choose one; I agree that it is better for another pull request. I have not looked at the endorsed library or at openapi-generator yet, I will check them and come back. I also updated the branch, which had a conflict in ChangeLog.md.

@spyhunter99

Copy link
Copy Markdown
Contributor

regarding gson/jackson, that's probably my fault. personally i try to avoid gson and have ran into countless problems serializing or deserializing json. jackson has always been the more pleasant experience for me. But i'm sure others have different experiences.

just my two cents

@spyhunter99

Copy link
Copy Markdown
Contributor

another thing to consider. We have a plugin system that enables a rest like interface through the plugin setup. It's kind of neat, but also kind of strange since it's so much different than in other frameworks. This enables a wiki plugin to bundle it's own rest capability with it. See WikiAjaxServlet and WikiAjaxDispatcherServlet

i'm not entirely sure if the openapi generator can be wired into this or not, but if it can, it should be

@arturobernalg

Copy link
Copy Markdown
Member Author

Thanks both. Juan Pablo, the separate module and Jackson instead of Gson are done in #650, which builds on this one and the next ones: the REST API is the module jspwiki-rest-api and its JSON is written with Jackson. I have not looked yet at the endorsed library or at openapi-generator.

Alex, about WikiAjaxServlet: I read WikiAjaxDispatcherServlet and I kept a plain servlet for this API for three reasons that come from how the dispatcher works. It maps /ajax/ServletName/action and takes anything else only from the parameter params, a list separated by commas, so a page name with a comma cannot be a parameter and the pages cannot be resources of the URL, as /api/v1/pages/Name is. It asks for the anti-CSRF token in every call, also in GET, which is right for the pages of the wiki but gets in the way of a client that is not a page. And it gives one permission for the whole servlet, while here it is the view permission of each page. The answers with 401, 403 and 404 and the OpenAPI file that a test compares with them describe the URLs as they are.

Plugins can keep bringing their own REST through WikiAjaxServlet, nothing changes for them. If you still prefer the API to go through the dispatcher, I can look at what it would need, but it would change the URLs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants