Getting started with the types API
The types REST API endpoint is available as of Sitevision 2023.11.1 and its accompanying "pin/unpin content" friend is available as of Sitevision 2024.01.1
The Types API was introduced in the Sitevision 2023.11.1 release. Types is a contextless REST API endpoint that is used to lookup page data in a structured manner - regardless of where the data is located in the page structure. A template defines the specific type and the contents of the template defines the fields of the type.
The "pin/unpin content" concept that was introduced in the Sitevision 2024.01.1 release complements the Types API by prohibiting page editors to inadvertently sabotage the types schema when working with specifik pages and their content.
Permissions
To properly setup the type and fields for the Types API, two permissions are required:
- MANAGE_TYPES_IDENTIFIERS permission is required to administer the type and fields for the Types API.
- MANAGE_PINNING permission is required to pin and unpin modules (i.e. "seal the fields" of the Types API).
These permissions should typically only be assigned to the role/roles of more advanced (super) users of the site.
Example schema - how to setup a type with mandatory and optional fields
The template depicts the type and the modules of the page depicts the fields of the type. The type name is given by the technical identifier of the template and the field names are given by the technical identifiers of each module.
Note that a module that is denoted as a field must have Headless support in order to provide data to consumers of the Types API. The Text module and the Image module of Sitevision has built-in Headless support. WebApp modules must explicitly implement Headless support to provide data.
Step 1 - Register the type
Navigate to the Templates view and open Properties for the designated Template. Locate the technical identifier and enter the name of the type. In this example we specify "activity" as the type name.
The name of the type is activity
Step 2 - Register the fields of the type
Fields of the type are depicted via some or all modules of the type (i.e. the Template). Open properties for the designated module/modules and locate the technical identifier section. Specify the name of the field. In this example we specify three fields: "title", "description" and "image". All three modules supports Headless (Text module and Image module).
The field name is title
The field name is description
The field name is image
Step 3 - Determine mandatory vs optional fields
The pin/unpin feature can be used to depict all mandatory fields (i.e. mandatory modules). A user that creates pages and articles typically can't delete pinned modules if the permissions are properly setup for the editor role of the site. Deleting a module that is specified as a field (or change the identifier) would screw up the intended type schema.
Right-click on the mandatory modules and select Pin in the menu to pin them. In this example we decide that the "title" and "description" fields are mandatory and the "image" field is optional. Hence we pin two modules.
The type schema is now properly setup so we publish the template.
Pin the modules that depicts the mandatory fields of the type
Step 4 - Start creating type entries
When the template is ready to use, we can allow the page editors to start creating content as usual, i.e. in this case - creating articles. In this example we create two articles.
This type entry has all fields of the type
This type entry has both mandatory fields of the type (optional image field is not part of this entry)
Step 5 - Use the Types API to extract data
The Types endpoint is part ot the Sitevision REST API. It is a contextless endpoint, i.e. is not bound to any node in the data/model tree of the site.
This is an example of the most basic usage of the Types API you can do - a GET request without any custom options. The type we created in step one is named "activity" and the site domain in this example is localhost.
GET https://localhost/rest-api/1/1/types/activity
[
{
"id": "5.5ea6678318d8cfb40d333",
"name": "Skateboarding",
"tags": [],
"fields": {
"title": {
"name": "Title",
"id": "12.5ea6678318d8cfb40d33b",
"type": "text",
"properties": {
"textContent": "Skateboarding"
}
},
"description": {
"name": "Description",
"id": "12.5ea6678318d8cfb40d33c",
"type": "text",
"properties": {
"textContent": "Skateboarding is a form of recreation and sport where a person rides standing balanced on a small board mounted on wheels."
}
},
"image": {
"name": "Image",
"id": "12.5ea6678318d8cfb40d33d",
"type": "image",
"properties": {
"image": {
"displayName": "skateboard.jpg",
"alt": "a skateboard in close-up",
"mimeType": "image/jpeg",
"URI": "/images/18.6d60aac518b471449f73d7/1656667621355/skateboard.jpg",
"URL": "https://localhost/images/18.6d60aac518b471449f73d7/1656667621355/skateboard.jpg",
"id": "18.6d60aac518b471449f73d7",
"caption": ""
}
}
}
}
},
{
"id": "5.5ea6678318d8cfb40d33f",
"name": "Jogging",
"tags": [],
"fields": {
"title": {
"name": "Title",
"id": "12.5ea6678318d8cfb40d347",
"type": "text",
"properties": {
"textContent": "Jogging"
}
},
"description": {
"name": "Description",
"id": "12.5ea6678318d8cfb40d348",
"type": "text",
"properties": {
"textContent": "Jogging is a form of running at a slow pace."
}
}
}
}
]The Types also supports custom options. The documentation is available as part of the REST API docs of your own site:
https://MY_DOMAIN/rest-api/doc/methods/types
NOTE! Access to the REST API docs requires the DEVELOPER permission and the REST API must also be enabled for the site.
Server-side invocation of the Types API
The Types endpoint can also be invoked server-side by WebApps and RESTApps via the RestApi utility. The Root Node is used as context.
// Get the RestApi utility and ResourceLocatorUtil
//
// a) In a WebApp/RESTApp you would use import:
// import restApi from '@sitevision/api/server/RestApi';
// import resourceLocatorUtil from '@sitevision/api/server/ResourceLocatorUtil';
//
// b) In a Script module or legacy WebApp/RESTApp you would use require:
// const restApi = require('RestApi');
// const resourceLocatorUtil = require('ResourceLocatorUtil');
const root = resourceLocatorUtil.getRootNode();
const options = { type: 'activity' };
const result = restApi.get(root, 'types', options);
if (result.statusCode >= 200 && result.statusCode < 300) {
// Handle the result.body data...
} else {
// Handle failed invocation...
}Do you want to subscribe to News from Sitevision Developer team? Subscribe here!