Using Versions for pages managed through REST API calls

Comments

9 comments

  • Avatar
    Nils Bier

    Hi Wybe,

    Please note, that the following REST endpoints are not officially supported and may change in upcoming releases without notice. Please test your tools heavily on a test system before using those REST endpoints productively.

    To better understand what the following REST calls are doing, let me give you a quick introduction how versioning a document works technically:
    As you already mentioned, there exists a page for each version of a document with the naming pattern ".<name> v<version>", we call those "dot-pages".
    To group versions of a document together, all the dot-pages of a document are the child of the same page, the "masterpage" (please have a look at the Scroll Versions glossary for further information about Dot-pages and master pages: https://help.k15t.com/scroll-versions/latest/glossary-112919376.html).

    So if you have a document "hello world" in version 1, 2 and 3, the pagetree (e.g. available via the "view in hierarchy") for this document would look like this:
    document

    -.hello world v1

    -.hello world v2

    -.hello world v3

    (in the standard page tree we're hiding those versioned pages)

    For most REST calls, you need to know the Id of the version in which you want to do something. The following REST call retrieves all versions together with their Ids in the specified space:
    GET <confluence>/rest/scroll-versions/1.0/versions/<spaceKey>

    To add a new version to an existing document, you first have to "create" the dot-page for that version - meaning that you create the ".xxxx vx" page . This can be done via this REST call:
    POST <confluence>/rest/scroll-versions/1.0/page/modify/<spaceKey>
    Together with the following form parameters: "masterPageId", "pageTitle", "versionId" and "changeType" (all Strings)
    "masterPageId": the Confluence page id of the masterpage of the document. 
    "pageTitle": the title for the document in this version
    "versionId": the Id of the version to be added to the document
    "changeType": use "Modify" if you want to add the version to the document. Use "Remove" to remove the document from this version

    If the document already exists for this version, the "changeType" field will be updated (the document removed or re-added to the version). Once the page is created, you can edit the content over the normal Confluence REST API (the response contains the Confluence Pagei Id of the newly created page).

    To add a completely new document in a specific version, use the following REST call. This will create the masterpage together with the dot-page for this version:
    POST <confluence>/rest/scroll-versions/1.0/page/new/<spaceKey>
    Together with the following form parameters: "parentConfluenceId", "pageTitle" and "versionId" (all Strings)
    "parentConfluenceId": the Confluence page Id of the masterpage of the parent document (not the id of a dot-page!)
    "pageTitle": the title of the new document
    "versionId": the id of the version in which the document should be created initially.

    Again, this call returns the page id of the newly created dot-page, with which you can edit the page through the normal Confluence REST API.

    I hope that helps. Please let us know if you need any further information.

    Best,

    Nils

    2
    Comment actions Permalink
  • Avatar
    Wybe Minnebo (Edited )

    Hello Nils,

    This helps tremendously! Thank you very much for your elaborate description.

    Best,
    Wybe

    1
    Comment actions Permalink
  • Avatar
    Wybe Minnebo (Edited )

    I've succesfully implemented the endpoints Nils suggested. For anyone watching, I did require a few additional headers on the request, which I didn't need for normal Confluence REST calls:

    • Content-Type: application/x-www-form-urlencoded: Avoids the HTTP 415 "Unsupported Media Type" error
    • X-Atlassian-Token: no-check: Avoids the HTTP403 "XSRF check failed" error

    Additionally, I used the GET <confluence>/rest/scroll-versions/1.0/pagetree/<spaceKey> to build an index of which pages were already versioned. It requires two query parameters, versionId and isShowToplevelPages (boolean), but also takes a bunch more. To see how it works, open your browsers network tab and look for it when browsing the Confluence backend.

    Once again, thanks Nils for your concise answer!

    - Wybe

    1
    Comment actions Permalink
  • Avatar
    Pavel

    Hello k15t!

    We are thinking about buying Scroll Versions.

    We have many spaces.

    Part of our documentation is written manually in Confluence. Here we plan to use versions of Scroll Versions.

    Other part is published to Confluence using the standard REST API. Here we do not plan to use versions.

    This content is in different spaces.

    Why does not the standard call work?

    POST /rest/content

    There are no versions in this space.

     

    Thanks,

    Pavel

    1
    Comment actions Permalink
  • Avatar
    Roman Serazhiev

    Hi Pavel.

    Could you please clarify that you would like to only publishing without having any versions created in the master space? This is not possible, at least one version has to be created in the master (source) space.

    Scroll Versions also has its own private APIs for creating pages, editing versioned pages, publishing, etc. Those API endpoints are not officially supported to be used by a user.

    If you could share what would you like to achieve, I will let you if it's possible to do and how.

    Cheers,
    Roman.

    0
    Comment actions Permalink
  • Avatar
    Pavel

    Hi Roman!

    Now we have many tools that create pages (some docs, reports, etc.) in different spaces using the standard Confluence REST API.

    We turned on trial Scroll Versions on our TEST server (Confluence 6.1.3). After that, the standard POST call stopped working (GET, PUT, DELETE continue to work) in all spaces.

    Why did it happen? Is there a reason in the Scroll Versions or have we done something wrong?

    You wrote: “This is not possible, at least one version has to be created in the master (source) space.”

    It is not true. The old standard Confluence XML-RPC method storePage continues to work and create page (https://developer.atlassian.com/server/confluence/confluence-xml-rpc-and-soap-apis/). It creates an unversioned page and no versions in space.

    I know about not official Scroll Versions REST API. But we do not want to spend time on changing our tools.

    I want to receive an answer "Yes" or "No".

    -- Yes - POST call stopped working because we turned on Scroll Versions

    -- No – another reason.

    If "Yes", is this your bug? Or you did it meaningly

     

    Thanks,

    Pavel

    0
    Comment actions Permalink
  • Avatar
    Roman Serazhiev

    Hi Pavel,

    Scroll Versions doesn't "disable" any of the Confluence's REST APIs as it uses them itself, therefore the answer is No.

    If you would like to use REST API to create or modify versioned pages in spaces where Scroll Versions is activated, you might need to use API endpoints provided by Scroll Versions due to a specific structure of pages in such space to achieve the functionality of having multiple versions in a single space (see Glossary for Dot Pages, Inheritance and Master Pages).

    If you would like to use API for non-versioned spaces, you should use Confluence REST API.

    Could provide a bit more information on how REST API "doesn't work" on your TEST instance so I could investigate further?

    Cheers,
    Roman.

    0
    Comment actions Permalink
  • Avatar
    Pavel

    Roman Thanks!

    I looked at our POST calls.

    As a result, I successfully completed the POST.

    The problem was with the encoding.

    We insert content with utf-8. But after Scroll Versions was turned on, no pages were created with POST calls. This Confluence instance is a full copy of another Confluence server, where pages are successfully created with POST calls and utf-8.

    I changed the encoding of the inserted data to UTF-8 without BOM or ANSI and completed the POST call.

    --Pavel

    0
    Comment actions Permalink
  • Avatar
    Roman Serazhiev

    Hi Pavel.

    I am glad that the problem is now resolved!

    P.S. If you are satisfied with Scroll Versions, it would be great if you could leave a rating or even a short customer review in the Atlassian Marketplace: https://marketplace.atlassian.com/plugins/com.k15t.scroll.scroll-versions/server/reviews.

    Cheers,
    Roman.

    0
    Comment actions Permalink

Please sign in to leave a comment.

Powered by Zendesk