How to create a child page to a parent page with XWiki REST API?

This is my first post on this site, and I want to let you know that English is not my native language. Please understand that there might be errors in my writing.

I'm facing an issue while trying to create a child page using the XWiki REST API within the Talend tRESTClient component. I have a parent page in XWiki, and I want to create a new child page under it programmatically.

I've tried several approaches, including using the POST and PUT methods with different URL variations, but so far, I haven't been successful. I keep getting errors, such as 404,405 or updating the parent page instead of creating a new child page.

Here is an example of a page I am trying to send (XML):

<page xmlns=\"http://www.xwiki.org\">
    <title>Page</title>
    <syntax>xwiki/2.1</syntax>
    <parent>xwiki:myspace.mypage</parent>
    <content>This is a new page</content>
</page>

Here are some examples of URLs I've tried (http request, put method): https://example.com/rest/wikis/xwiki/spaces/myspace/pages/mychildpage https://example.com/rest/wikis/xwiki/spaces/myspace/pages/mypage https://example.com/rest/wikis/xwiki/spaces/myspace/pages/mypage/mychildpage

Here is a link to the documentation I use:(https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI)

Has anyone successfully created a child page using the XWiki REST API? Could you please share the correct request format or any insights on how to achieve this?

Any help or guidance would be highly appreciated.

Solution

The "parent" notion has been deprecated in XWiki. It is still kept for backwards compatibility, but what you really want to create is a Nested Page (i.e. a subpage which technically also brings in a new subspace). This migration guide might be useful in better understanding what is going on: https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/ContentOrganization/NestedPagesMigration/

Make sure you go through this section of the documentation that explains how to use the API, particularly the tutorial: https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI#HUsingtheRESTfulAPI

If not clear on the request body from the example in the documentation, you can just do a GET first and send the same payload on the PUT, just with modified fields, accordingly.

In short, the URL format is:

/wikis/{wikiName}/spaces/{spaceName}[/spaces/{nestedSpaceName}]*/pages[?start=offset&number=n]

For your example, this translates to:

PUT https://example.com/rest/wikis/xwiki/spaces/myspace/spaces/mypage/spaces/mychildpage/pages/WebHome

Explanation:

Nested Pages can not be terminal pages if they want to have children. This means that your parent page reference must be xwiki:myspace.mypage.WebHome (space "myspace", subspace "mypage", page "WebHome"), or you will simply not be able to add child pages for it.

The reference of your child page with such a parent will then be: xwiki:myspace.mypage.mychildpage.WebHome (space "myspace", subspace "mypage", subspace "mychildpage", page "WebHome"), in the (default) case where the child page is also a NonTerminal page that will support further children.

Note: If not already clear, each space in XWiki has a homepage called "WebHome", even if it is not always visible in the URL, e.g. "/xwiki/bin/view/Main/" is the same as "/xwiki/bin/view/Main/WebHome" (which is you actual page).

Bonus: Technically, you can also create Terminal child pages, but it's not really recommended, unless you really know what you are doing. For that case, you reference would be xwiki:myspace.mypage.mychildpage (space "myspace", subspace "mypage", page "mychildpage") but, as mentioned, it will not support further children.

Hope this helps.