Add Viewports Using the REST API | K15t

Scroll Sites provides a REST API for creating new viewports. To create a viewport you must send a POST request to the REST endpoint, containing the viewport definition as JSON structure in the request body.

POST application/json to <BASE_URL>/rest/scroll-viewport/1.0/viewport/<SPACE_KEY>

{
    "domainName": "",
    "themeId": "com.k15t.scroll.scroll-viewport:scroll-webhelp-theme",
    "pathPrefix": "/test",
    "repository": {
        "_type": "ConfluenceSpaceRepository",
        "spaceKey": "TEST",
        "pagesEnabled": true
    }
}

The above is a rather minimal example where only pages are enabled in a space (whereas blogposts are not) and hierarchical page paths are used.

You can always retrieve a complete example for the config JSON structure by sending a GET request:

GET <BASE_URL>/rest/scroll-viewport/1.0/viewport/<SPACE_KEY>/new

 {
    "id": "C0A812D10152D03A986C6F6A37B2BA96",
    "domainName": "",
    "themeId": "com.k15t.scroll.scroll-viewport:scroll-webhelp-theme",
    "draft": true,
    "previewUrl": "/confluence/plugins/scroll-viewport/draft/C0A812D10152D03A986C6F6A37B2BA96",
    "viewportUrl": "http://localhost:1990/confluence/plugins/scroll-viewport/draft/C0A812D10152D03A986C6F6A37B2BA96",
    "pathPrefix": "",
    "repository": {
        "_type": "ConfluenceSpaceRepository",
        "spaceKey": "TEST",
        "pagesEnabled": true,
        "pagePathPrefix": "",
        "pageUrlNaming": {
            "_type": "HierarchicalUrlNaming"
        },
        "blogPostsEnabled": false,
        "blogPostPathPrefix": "/blog",
        "blogPostUrlNaming": {
            "_type": "DefaultBlogPostUrlNaming"
        },
        "repoProperties": []
    }
}

Available JSON fields

Name	API Default Value	Description
^id	<empty>	When creating a new viewport this field should NOT be contained in the config structure.
^domainName	<empty>	The value of the Domain Name field in the viewport config UI.
^themeId	^{com.k15t.scroll.scroll-viewport:scroll-webhelp-theme}	The ID of the theme to use for the new viewport.
^draft	^false	This should either be removed or set to "`false`" when creating a new viewport
^previewUrl ^viewportUrl	<empty>	These have no effect when creating a new viewport. It is recommended to omit these fields.
^pathPrefix	<empty>	The path prefix your viewport will be available at. Only a single viewport per domain name can have a blank path prefix. In the viewport config UI this defaults to the lowercase space key with a leading slash.
^{repository._type}		This must be set to "`ConfluenceSpaceRepository`".
^{repository.spaceKey}		The key of the space you want to assign the viewport to. Must be the same as in the POST URL.
^{repository.pagesEnabled} ^{repository.blogPostsEnabled}	false	Define what content your viewport provides. Make sure to set at least one of them to "`true`".
^{repository.pagePathPrefix} ^{repository.blogPostPathPrefix}	<empty>	The path prefixes for pages and blogposts. If both pages and blog posts are enabled these must NOT be identical. In the viewport config UI the prefix for pages is empty by default and the prefix for blogposts is "`/blog`".
^{repository.pageUrlNaming._type}	^{HierarchicalUrlNaming}	Defines how page URLs are created. There are two options: `HierarchicalUrlNaming` `FlatUrlNaming`
^{repository.blogPostUrlNaming._type}	^{DefaultBlogPostUrlNaming}	Defines how blog post URLs are created. Currently only "`DefaultBlogPostUrlNaming`" is supported.
^{repository.repoProperties}	<empty>	Should NOT be included when creating a new viewport.