Sitevision Model REST API
Sitevision provides a built-in Model REST API that operates on the JCR data tree model that is also accessible via the Sitevision Public API. The authentication and permissions that are required to access the data via the REST API is exactly the same as it is in the Sitevision editor and via the Public API.
Activate the API
The Model REST API is bundled with all Sitevision installations, but it must be explicitly activated on the website. The Model REST API is activated (enabled) under the Site settings in the Sitevision editor. When activated, access can also be restricted to certain users or user groups.
The REST API settings is available via the Site settings
REST API documentation
Enabling the REST API also exposes the REST API documentation to all users that has the DEVELOPER permission!
REST API documentation overview
Be sure to log on to the website and ensure your user has the DEVELOPER permission. The REST API documentation for your REST API-enabled website is available at:
<protocol> :// <domain> / rest-api / doc
Nodes
Browsing the JCR Model
When you enter the REST API documentation you see the Nodes view. The JCR Model tree can be browsed via the links in the left menu. All available Methods/Operations will be displayed for each Node you navigate to.
REST API documentation for the Online index
Selecting a Method
When you have browsed to a Node in the JCR Model tree and selected a Method/Operation, its documentation is displayed. The documentation specifies the supported http verbs (GET, POST, PUT, DELETE) and the data requirements. It often also gives an example of input data and the corresponding JSON result.
REST API documentation for the Search method on the Online index
REST API URLs
Each node and endpoint has two different URLs that can be used.
- JCR Name Path-based URL
- JCR Identifier-based URL
There are two REST API URLs to each endpoint
REST API URL Pattern
The pattern of a REST API URL is:
<protocol> :// <domain> / rest-api / <api version> / <model version> / <path | identifier> / <method>
Where:
- The <api version> specifies which version of the REST API that should be executed. There are currently only one version, so for now it should always be "1".
- The <model version> specifies what model version to use. For offline data it should be "0" and for online data it should be "1". In the REST API documentation "0" is always used (so a developer can get full data even if the website or certain pages have not yet been published) but when writing actual production code that invokes the REST API - "1" should in almost all cases be used!
- The <path | identifier> specifies a Node in the JCR Model. As mentioned below, the identifier is always recommended over the path.
- The <method> specifies the actual endpoint. It is always the lowercased name of the actual Method.
Example:
https://mydomain.se/rest-api/1/1/303.online-7.0/search
The <model version> should typically be 1 ("online") in a REST URL when used externally!
- Sitevision editors that are working in the Sitevision editor UI use/view the "offline" version (0). This version will contain unpublished material.
- Site visitors always use/view the "online" model version (1). This version will only contain published material.
=> External invokers of the REST API should typically behave as typical site visitors, i.e. use the "online" model version (1).
Example:
https://mydomain.se/rest-api/1/1/303.online-7.0/search
1. The Path-based URL
The parts of a JCR Node Path-based URL contains JCR Node Names (as of javax.jcr.Node.getName() values). Note that not all chars are allowed in a JCR Node Name! The JSR 283 specification states that these chars are forbidden and must be replaced:
| Illegal character | Substitution character |
|---|---|
| / (U+002F) "slash" | U+F02F (URL-encoded as: %EF%80%AF) |
| * (U+002A) "asterix" | U+F02A (URL-encoded as: %EF%80%AA) |
| : (U+003A) "colon" | U+F03A (URL-encoded as: %EF%80%BA) |
| [ (U+005B) "left bracket" | U+F05B (URL-encoded as: %EF%81%9B) |
| ] (U+005D) "right bracket" | U+F05D (URL-encoded as: %EF%81%9D) |
| | (U+007C) "pipe" | U+F07C (URL-encoded as: %EF%81%BC) |
As explained above, you can never have a name like "some/name" as part when using the Path-based URL to invoke the REST API. That name is simply not a JCR Node Name!
The proper name to use would be something like "somename" (i.e. the presumed slash should be a U+F02F character). URL-encoded it would be: "some%EF%80%AFname"
Sitevision tries to be lenient and forgiving even if a part of a Path-based REST API URL contains illegal characters. As a precaution, all potential illegal characters will be substituted using EndecUtil.escapeJcrName before the final resource is resolved. This will handle some invalid (non-JCR) names but some cases simply can not be solved by Sitevision:
- A part that contains the "slash" character will pollute the "real" URL and be handled as a "real" slash (i.e. a http URL path separator). The slash character must always be substituted!
- A part that contains the "pipe" character will typically be blocked by the server as it's not part of the official http URL standard. The pipe character must always be substituted!
2. The Identifier-based URL
The JCR Identifier-based URL contains a Node Identifier (as of javax.jcr.Node.getIdentifier() value).
Always use the Identifier-based URL whenever possible!
The Identifier-based URL is significantly faster than the path-based URL and it is also safer since it guarantees there will never be a name collision!
The REST API Console
The REST API Console can be used to test invocations of REST API endpoints.
- Enter the endpoint URL (i.e. paste in the URL you typically copied when you browsed the JCR Model tree and selected a Method available for that specific Node)
- Potentially enter input data required/supported by the endpoint
- Select type (Http Verb).
NOTE! This is REAL invocations, be careful if you do a POST, PUT or a DELETE! - Press the submit button
- Voila! See the invocation result!
The REST API Console parts
Console Example
Example of REST API Console usage