Include optional HTML rendering in /pages REST endpoint

Development
,
1

Hi everyone,

This proposal is about providing a rendered version of a page’s content on the /pages endpoint.

XWiki supports many syntaxes, and an application relying on the REST API to fetch knowledge from an XWiki instance might stumble upon pages they don’t know how to handle. This is an issue we have in Cristal currently, since we only support markdown so far (although support for xwiki/2.1 is definitely planned) we require custom code (a XWiki extension) to render content in HTML for all other syntaxes in order to display pages. Having this implemented would help us drop this code to align ourselves with the standard API.

There are at least two ways to implement this if we go with this proposal:

  1. An opt-in boolean flag (renderHtml), that we would always use in Cristal since we cannot know beforehand the syntax of the page we are fecthing,
  2. An optional supportedSyntaxes parameter that, if set, would indicate which syntaxes are supported by the client and thus should not lead to a rendered version. Not setting it at all would not change the current behavior.

Personally, I would prefer option 2 to avoid unnecessary rendering when fetching a page, or avoid fetching it a first time to check its syntax.

What do you think?

2

+1 as long as it’s possible to define an empty set of supported syntaxes (i.e., simulating option 1).

3

I’m not sure I understand the proposal. Isn’t the topic about also returning a rendered version of the page in addition to the raw page content?

If so, then why not simply add an optional renderSyntaxes parameters that would list all syntaxes into which the page must be rendered?

Now the main problem is not that, but it’s that for rendering a page you need to know the full context (current language, current user, query string parameters, etc). How are you proposing to pass the context elements?

Thx

4

In the context of Cristal, the goal is to rely on server-side rendering as a fallback when there is no client-side parser available for the page syntax.
In addition, we’d like to do so in the smallest number of queries.

Option 1: introduce a dedicated “rendering” rest endpoint

In this case, we might end up with two rest requests:

  1. call the /pages endpoint (first rest request)
  2. check if we have a parser for the page syntax
  3. if not, call the rendering rest endpoint (second rest request)

Option 2: have the rendering as part of the /pages rest endpoint

  1. get the list of parsers client-side (first and single rest request)
  2. call the /pages rest endpoint and pass the set of supported syntaxes
    1.1 if the syntax of the page is part of the supported syntaxes, no rendering is done
    1.2 otherwise, the rendering is performed and returns

The advantage of option 2 is that a single query is performed.
The cons is that because of the rendering, the request can be significantly slower to return.
Consequently, part of the UI that could be rendered with the data for the /pages rest endpoint (e.g., breadcrumb), will be blocked waiting for the rendered result too.

Thanks for pointing that out. That’s indeed a point we overlooked when brainstorming the issue.
Do we have documentation of the list of parameters required for rendering?

5

I think a first level approximation is: https://extensions.xwiki.org/xwiki/bin/view/Extension/Rendering%20Module/Async/#HStandardcontextentries

But it’s probably not 100% complete. It contains what we have needed up to know when writing async code.

1 Like
6

You should already have the current user and locale in the context (not necessarily in the XWikiContext itself, but it will be found, same as any page /view/).

There is no requirement. It’s more if you need to render the document with a specific context (execute the page with a different current document, in a different current wiki, etc.).