Chapter 8. REST API

⁠Chapter 8. REST API

⁠8.1. Overview

The portal provides a REST API to portal entities such as Sites, Pages, and Navigation. All data is sent and received as JSON.

Report a bug

⁠8.1.1. Base URL

There are two base URLs for the REST API. One that will be used if you need to authenticate and one that can be used to access resources anonymously.

Anonymous Base URL: http://<host>:<port>/rest/managed-components/api
Authenticated Base URL: http://<host>:<port>/rest/private/managed-components/api

Report a bug

⁠8.1.2. Authentication

The REST API supports basic authentication. Below is an example of using basic authentication in curl command.

curl -u <username> http://<host>:<port>/rest/private/managed-components/api

This allows users to access resources they have access to depending on the portal entity permissions.

Note

Only members of the group /platform/administrators are allowed to add, update, or delete resources.

Report a bug

⁠8.1.3. Content Type

Since all data is sent and received using JSON, appropriate HTTP headers need to be included in each HTTP request.

For clients receiving data the following HTTP header needs to be included in the request

Accept: application/json

For clients sending data the following HTTP header needs to be included in the request

Content-Type: application/json

Report a bug

⁠8.1.4. Localization

Localization is supported for navigation nodes that have localized displayNames. To specify the language simply add the Accept-Language header to the HTTP request.

⁠

Example 8.1. French Header

This examples describes the Accept-Language header used for French localization.

Accept-Language: fr

Report a bug

⁠8.2. Resources

The following sections describe the resources available in the REST API.

Important

All URLs in the Example responses featured in this section are relative to the Base URL.

Report a bug

⁠8.2.1. Sites

⁠8.2.1.1. List Sites

Sites are organized by site type, where site-type can be site , space , or dashboard .

⁠

Example 8.2. Listing Sites using GET

This example describes the syntax required to list site types.

GET /api/{site-type}s/

Note

The 's' at the end of the URL is important. Space resolves to /api/spaces/ and dashboard resolves to /api/dashboards/.

⁠

Table 8.1. Additional Parameters for site-type

Parameter	Type	Default	Description
emptySites	boolean	false	Indicates to include empty sites (sites w/out pages or navigation)
offset	int	0	The offset of the results in a paginated request
limit	int	15	The maximum number of results to return in a paginated request

⁠

Example 8.3. List Sites using GET Request and Response

This example lists the sites that are available and their corresponding resource location. This should be used by clients instead of hard coding every location or URL.

GET /api/sites

HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "name" : "classic",
        "type" : "site",
        "url" : "/api/sites/classic"
    },
    {
        "name" : "mobile",
        "type" : "site",
        "url" : "/api/sites/mobile"
    }
]

Note

The url element is the full URL but for sake of brevity it is relative for the examples in this document.

Report a bug

⁠8.2.1.2. Retrieve a Site

To retrieve a site named site-name the following syntax applies.

GET /api/{site-type}s/{site-name}

⁠

Example 8.4. Retrieve a Site Request and Response

This example shows how to retrieve the Classic site.

GET /api/sites/classic

HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "classic",
    "type" : "site",
    "displayName" : "Classic",
    "description" : "GateIn default portal",
    "skin" : "Default",
    "locale" : "en",
    "access-permissions" : ["Everyone"],
    "edit-permissions" : ["*:/platform/administrators"],
    "attributes" : [
        {
            "key" : "showPortletInfo",
            "value" : "false"
        },
        {
            "key" : "sessionAlive",
            "value" : "onDemand"
        }
    ],
    "pages" : {"url" : "/api/sites/classic/pages"},
    "navigation" : {"url" : "/api/sites/classic/navigation"}
}

Note

The url element is the full URL but for sake of brevity it is relative for the examples in this document.

Report a bug

⁠8.2.1.3. Create a site

To create a site named site-name, the following syntax applies:

POST /api/{site-type}s/{site-name}

⁠

Example 8.5. Create a Site Request and Response

This example creates a site named 'foo'.

POST /api/sites/foo

HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "foo",
    "type" : "site",
    "displayName" : "Basic Portal",
    "description" : "This is basic portal template",
    "skin" : "Default",
    "locale" : "en",
    "access-permissions" : ["Everyone"],
    "edit-permissions" : ["*:/platform/administrators"],
    "attributes" : [{
        "key" : "sessionAlive",
        "value" : "onDemand"
    }],
    "pages" : {"url" : "/api/sites/foo/pages"},
    "navigation" : {"url" : "/api/sites/foo/navigation"}
}

Note

The url element is the full URL but for sake of brevity it is relative for the examples in this document.

Report a bug

⁠8.2.1.4. Delete a site

To delete a site named site-name, the following syntax applies:

DELETE /api/{site-type}s/{site-name}

⁠

Example 8.6. Delete a Site Request and Response

This example deletes a site named 'foo'

DELETE /api/sites/foo

HTTP/1.1 200 OK
Content-Type: application/json

Report a bug

⁠8.2.1.5. Update a site

To update a site named site-name, the following syntax applies:

PUT /api/{site-type}s/{site-name}

⁠

Example 8.7. Update a Site Request and Response

This example updates the site 'classic' with a new description "The Classic site shipped with the product".

PUT /api/sites/classic

Content-Type: application/json
{
   "description" : "The Classic site shipped with the product"
}

HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "classic",
    "type" : "site",
    "displayName" : "Classic",
    "description" : "The Classic site shipped with the product !",
    "skin" : "Default",
    "locale" : "en",
    "access-permissions" : ["Everyone"],
    "edit-permissions" : ["*:/platform/administrators"],
    "attributes" : [
        {
            "key" : "showPortletInfo",
            "value" : "false"
        },
        {
            "key" : "sessionAlive",
            "value" : "onDemand"
        }
    ],
    "pages" : {"url" : "/api/sites/classic/pages"},
    "navigation" : {"url" : "/api/sites/classic/navigation"}
}

Note

The url element is the full URL but for sake of brevity it is relative for the examples in this document.

Report a bug

⁠8.2.2. Pages

⁠8.2.2.1. List Pages

To list pages in a site named site-name, the following syntax applies:

GET /api/{site-type}s/{site-name}/pages

⁠

Table 8.2. list-pages Additional Attributes

Parameter	Type	Default	Description
offset	int	0	The offset of the results in a paginated request
limit	int	15	The maximum number of results to return in a paginated request

⁠

Example 8.8. List all Pages Request and Response

This example shows how to list all pages for the site 'classic'.

GET /api/sites/classic/pages

HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "name" : "homepage",
        "siteType" : "site",
        "siteName" : "classic",
        "url" : "/api/sites/classic/pages/homepage"
    },
    {
        "name" : "register",
        "siteType" : "site",
        "siteName" : "classic",
        "url" : "/api/sites/classic/pages/register"
    },
    {
        "name" : "sitemap",
        "siteType" : "site",
        "siteName" : "classic",
        "url" : "/api/sites/classic/pages/sitemap"
    }
]

Note

The url element is the full URL but for sake of brevity it is relative for the examples in this document.

Report a bug

⁠8.2.2.2. Retrieve a page

To retrieve a page named page-name, the following syntax applies:

GET /api/{site-type}s/{site-name}/pages/{page-name}

⁠

Example 8.9. Retrieve a Page Request and Response

This example shows how to retrieve the page 'homepage'

GET /api/sites/classic/pages/homepage

HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "homepage",
    "displayName" : "Home Page",
    "description" : null,
    "access-permissions" : ["Everyone"],
    "edit-permissions" : ["*:/platform/administrators"]
}

Report a bug

⁠8.2.2.3. Create a page

To create a page named page-name, the following syntax applies:

POST /api/{site-type}s/{site-name}/pages/{page-name}

⁠

Example 8.10. Create a New Page Request and Response

The following example creates a page named 'newpage'.

POST /api/sites/classic/pages/newpage

HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "newpage",
    "displayName" : "newpage",
    "description" : null,
    "access-permissions" : ["Everyone"],
    "edit-permissions" : ["*:/platform/administrators"]
}

Report a bug

⁠8.2.2.4. Delete a page

To delete a page named page-name, the following syntax applies:

DELETE /api/{site-type}s/{site-name}/pages/{page-name}

⁠

Example 8.11. Delete a Page Request and Response

This example deletes a page named 'newpage'.

DELETE /api/sites/classic/pages/newpage

HTTP/1.1 200 OK
Content-Type: application/json

Report a bug

⁠8.2.2.5. Update a page

To update a page named page-name, the following syntax applies:

PUT /api/{site-type}s/{site-name}/pages/{page-name}

⁠

Example 8.12. Update Page Description Request and Response

This example updates the page 'homepage' with a new description.

PUT /api/sites/classic/pages/homepage

Content-Type: application/json
{
   "description" : "The default homepage"
}

HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "homepage",
    "displayName" : "Home Page",
    "description" : "The default homepage",
    "access-permissions" : ["Everyone"],
    "edit-permissions" : ["*:/platform/administrators"]
}

Report a bug

⁠8.2.3. Navigation

⁠8.2.3.1. Retrieve Navigation

To update a page named site-name, the following syntax applies:

GET /api/{site-type}s/{site-name}/navigation

⁠

Table 8.3. Retrieve Navigation Parameters

Parameter	Type	Default	Description
scope	int	n/a	Specifies how many nodes to load (-1 for all)

Below is an example of retrieving the navigation for the site 'classic'

⁠

Example 8.13. Request

GET /api/sites/classic/navigation

⁠

Example 8.14. Response

HTTP/1.1 200 OK
Content-Type: application/json
{
    "priority" : 1,
    "siteType" : "site",
    "siteName" : "classic",
    "nodes" : [
        {
            "name" : "home",
            "url" : "/api/sites/classic/navigation/home"
        },
        {
            "name" : "sitemap",
            "url" : "/api/sites/classic/navigation/sitemap"
        }
    ]
}

Note

The url element is the full URL but for sake of brevity it is relative for the examples in this document.

⁠

Example 8.15. Scope Parameter Request and Response

This example uses the scope parameter to load more nodes which will include the actual node representation in the response

GET /api/sites/classic/navigation?scope=1

HTTP/1.1 200 OK
Content-Type: application/json
{
    "priority" : 1,
    "siteType" : "site",
    "siteName" : "classic",
    "nodes" : [
        {
            "name" : "home",
            "uri" : "/portal/classic/home",
            "isVisible" : true,
            "visibility" : {"status" : "VISIBLE"},
            "iconName" : null,
            "displayName" : "Home",
            "displayNames" : [...]
            "children" : null,
            "page" : {
                "pageName" : "homepage",
                "siteName" : "classic",
                "siteType" : "site",
                "url" : "/api/sites/classic/pages/homepage"
            }
        },
        {
            "name" : "sitemap",
            "uri" : "/portal/classic/sitemap",
            "isVisible" : true,
            "visibility" : {"status" : "VISIBLE"},
            "iconName" : null,
            "displayName" : "SiteMap",
            "displayNames" : [...]
            "children" : null,
            "page" : {
                "pageName" : "sitemap",
                "siteName" : "classic",
                "siteType" : "site",
                "url" : "/api/sites/classic/pages/sitemap"
            }
        }
    ]
}

Note

The url element is the full URL but for sake of brevity it is relative for the examples in this document.

Report a bug

⁠8.2.3.2. Retrieve a node

To retrieve a node with path node-path, the following syntax applies:

GET /api/{site-type}s/{site-name}/navigation/{node-path}

⁠

Table 8.4. Node Path Parameters

parameter	type	default	description
scope	int	n/a	Specifies how many nodes to load (-1 for all)

⁠

Example 8.16. Retrieve a Node Request and Response

This example retrieves the node 'home'.

GET /api/sites/classic/navigation/home

HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "home",
    "uri" : "/portal/classic/home",
    "isVisible" : true,
    "visibility" : {"status" : "VISIBLE"},
    "iconName" : null,
    "displayName" : "Home",
    "displayNames" : [...]
    "children" : null,
    "page" : {
        "pageName" : "homepage",
        "siteName" : "classic",
        "siteType" : "site",
        "url" : "/api/sites/classic/pages/homepage"
    }
}

You can control the displayName value for localized nodes with the Accept-Language header.

⁠

Example 8.17. Accept-Language Request and Response

This example retrieves the node 'home' to display the displayName in French.

GET /api/sites/classic/navigation/home
Accept-Language: fr

HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "home",
    "uri" : "/portal/classic/home",
    "isVisible" : true,
    "visibility" : {"status" : "VISIBLE"},
    "iconName" : null,
    "displayName" : "Accueil",
    "displayNames" : [...]
    "children" : null,
    "page" : {
        "pageName" : "homepage",
        "siteName" : "classic",
        "siteType" : "site",
        "url" : "/api/sites/classic/pages/homepage"
    }
}

Note

The url element is the full URL but for sake of brevity it is relative for the examples in this document.

Report a bug

⁠8.2.3.3. Create a node

To create a node with path node-path, the following syntax applies:

POST /api/{site-type}s/{site-name}/navigation/{node-path}

⁠

Example 8.18. Create a Node Request and Response

This example creates a new node 'newnode' under the home navigation node.

POST /api/sites/classic/navigation/home/newnode

HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "newnode",
    "uri" : "/portal/classic/home/newnode",
    "isVisible" : true,
    "visibility" : {"status" : "VISIBLE"},
    "iconName" : null,
    "displayName" : "newnode",
    "children" : null,
    "page" : null
}

Report a bug

⁠8.2.3.4. Delete a node

To delete a node with path node-path, the following syntax applies:

DELETE /api/{site-type}s/{site-name}/navigation/{node-path}

⁠

Example 8.19. Delete Node Request and Response

This example deletes a node 'newnode'.

DELETE /api/sites/classic/navigation/home/newnode

HTTP/1.1 200 OK
Content-Type: application/json

Report a bug

⁠8.2.3.5. Update a node

To update a node with path node-path, the following syntax applies:

PUT /api/{site-type}s/{site-name}/navigation/{node-path}

⁠

Example 8.20. Update Node Request and Response

Below is an example of updating the node 'home' to point to the sitemap page rather then the homepage.

PUT /api/sites/classic/navigation/home

Content-Type: application/json
{
   "page" : {
        "pageName" : "sitemap",
        "siteName" : "classic",
        "siteType" : "site"
   }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "home",
    "uri" : "/portal/classic/home",
    "isVisible" : true,
    "visibility" : {"status" : "VISIBLE"},
    "iconName" : null,
    "displayName" : "Test",
    "displayNames" : [...]
    "children" : null,
    "page" : {
        "pageName" : "sitemap",
        "siteName" : "classic",
        "siteType" : "site",
        "url" : "/api/sites/classic/pages/sitemap"
    }
}

Note

The url element is the full URL but for sake of brevity it is relative for the examples in this document.

⁠

Example 8.21. Update displayName Request and Response

This example updates the English localized displayName to 'Home Page'.

PUT /api/sites/classic/navigation/home

Content-Type: application/json
{
    "displayNames" : [
        {
            "value" : "ホーム",
            "lang" : "ja"
        },
        {
            "value" : "Home Page",
            "lang" : "en"
        },
        {
            "value" : "首頁",
            "lang" : "zh-TW"
        },
        {
            "value" : "Domů",
            "lang" : "cs"
        },
        {
            "value" : "Accueil",
            "lang" : "fr"
        },
        {
            "value" : "主页",
            "lang" : "zh"
        },
        {
            "value" : "Главная",
            "lang" : "ru"
        },
        {
            "value" : "ترحيب",
            "lang" : "ar"
        },
        {
            "value" : "Trang chủ",
            "lang" : "vi"
        },
        {
            "value" : "Home",
            "lang" : "nl"
        },
        {
            "value" : "Inicio",
            "lang" : "es"
        },
        {
            "value" : "Principal",
            "lang" : "pt-BR"
        },
        {
            "value" : "Startseite",
            "lang" : "de"
        },
        {
            "value" : "홈",
            "lang" : "ko"
        },
        {
            "value" : "Home",
            "lang" : "it"
        },
        {
            "value" : "Додому",
            "lang" : "uk"
        },
        {
            "value" : "गृह पृष्‍ठ",
            "lang" : "ne"
        }
    ]
}

HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "home",
    "uri" : "/portal/classic/home",
    "isVisible" : true,
    "visibility" : {"status" : "VISIBLE"},
    "iconName" : null,
    "displayName" : "Home Page",
    "displayNames" : [
        {
            "value" : "ホーム",
            "lang" : "ja"
        },
        {
            "value" : "Home Page",
            "lang" : "en"
        },
        {
            "value" : "首頁",
            "lang" : "zh-TW"
        },
        {
            "value" : "Domů",
            "lang" : "cs"
        },
        {
            "value" : "Accueil",
            "lang" : "fr"
        },
        {
            "value" : "主页",
            "lang" : "zh"
        },
        {
            "value" : "Главная",
            "lang" : "ru"
        },
        {
            "value" : "ترحيب",
            "lang" : "ar"
        },
        {
            "value" : "Trang chủ",
            "lang" : "vi"
        },
        {
            "value" : "Home",
            "lang" : "nl"
        },
        {
            "value" : "Inicio",
            "lang" : "es"
        },
        {
            "value" : "Principal",
            "lang" : "pt-BR"
        },
        {
            "value" : "Startseite",
            "lang" : "de"
        },
        {
            "value" : "홈",
            "lang" : "ko"
        },
        {
            "value" : "Home",
            "lang" : "it"
        },
        {
            "value" : "Додому",
            "lang" : "uk"
        },
        {
            "value" : "गृह पृष्‍ठ",
            "lang" : "ne"
        }
    ],
    "children" : null,
    "page" : {
        "pageName" : "homepage",
        "siteName" : "classic",
        "siteType" : "site",
        "url" : "/api/sites/classic/pages/homepage"
    }
}

Note

The url element is the full URL but for sake of brevity it is relative for the examples in this document.

Note

We have to include all the displayNames since the REST API will overwrite the values on the server with whatever we supply in the request.

Since the REST API overwrites the displayNames field we can delete existing displayNames by simply not including them.

⁠

Example 8.22. Deleting All Localized Display Names Except for English Request and Response

This example deletes all localized displayNames except for English.

PUT /api/sites/classic/navigation/home

Content-Type: application/json
{
    "displayNames" : [
        {
            "value" : "Home",
            "lang" : "en"
        }
    ]
}

HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "home",
    "uri" : "/portal/classic/home",
    "isVisible" : true,
    "visibility" : {"status" : "VISIBLE"},
    "iconName" : null,
    "displayName" : "Home",
    "displayNames" : [
        {
            "value" : "Home Page",
            "lang" : "en"
        }
    ],
    "children" : null,
    "page" : {
        "pageName" : "homepage",
        "siteName" : "classic",
        "siteType" : "site",
        "url" : "/api/sites/classic/pages/homepage"
    }
}

Note

The url element is the full URL but for sake of brevity it is relative for the examples in this document.

⁠

Example 8.23. Removing Localized Display Names Request and Response

This example removes all localized displayNames from the home navigation node and replaces them with a non-localized (simple) displayName 'Home'.

PUT /api/sites/classic/navigation/home

Content-Type: application/json
{
    "displayName" : "Home"
}

HTTP/1.1 200 OK
Content-Type: application/json
{
    "name" : "home",
    "uri" : "/portal/classic/home",
    "isVisible" : true,
    "visibility" : {"status" : "VISIBLE"},
    "iconName" : null,
    "displayName" : "Home",
    "displayNames" : [{"value" : "Home"}]
    "children" : null,
    "page" : {
        "pageName" : "homepage",
        "siteName" : "classic",
        "siteType" : "site",
        "url" : "/api/sites/classic/pages/homepage"
    }
}

Report a bug