Skip to main content

API Reference

Sitecore hosted API endpoints#

These are the endpoints for services that provide content from Sitecore to your app.

Map service#

Map Service returns all pages in a hierarchical structure in JSON that are included in the scope for the given site configuration. The map service uses a flat JSON object, simplifying customizations and bringing first-class wildcard-item support.

You are able to control the scope of what gets included / excluded into Map Service via configuration, learn more here.

Usage#

GET: /uniform/api/content/<site-configuration-name>/map?uniform_token=<token>

where:

  • <site-configuration-name> is equal to the name of your site configuration site (e.g website). Learn more about Site Configuration here.
  • <token> is the value of the Uniform.API.Token setting set during Uniform Connector configuration

This service accepts the additional querystring parameter uniform_preview=true|false. Add ?uniform_preview=true to the request will have it execute go against Sitecore's master database, which is useful for debugging.

Sample output#

{   "isPage":true,   "lastModified":"2020-05-22T15:02:34",   "revision":"228357e9-5441-41ac-a6a6-d478cab07f19",   "children":{      "product-locator":{         "isPage":true,         "lastModified":"2020-01-10T19:30:52",         "revision":"2ef2f584-c46d-42a5-a4fe-42d82e52fadc",         "name":"product-locator",         "id":"69727f3d-f39b-4d03-ad40-0b81e4134d71",         "template":"BasePage"      },      "contact-us":{         "isPage":true,         "lastModified":"2020-01-10T19:25:22",         "revision":"ec484005-daed-466e-a163-777c348bbadd",         "name":"contact-us",         "id":"726180d9-ff11-49ff-ab00-6625d49db130",         "template":"BasePage"      }   },   "name":"Home",   "id":"3e294674-176d-40b8-9d3c-ef76ba8e7825",   "template":"Home"}

Map service inclusion / exclusion rules#

The rules are used to control which items are included in the output from the map service.

Rule evaluation#
  • If no include rules are specified, an item is included in the map unless it is matched by an exclude rule.
  • If at least one include rule is specified, an item is excluded from the map unless it is matched by an include rule.
  • If an item matches both an include rule and an exclude rule, the item is included.

The logic for rule evaluation may be changed in a future version, especially with respect to what happens when an item matches both an include rule and an exclude rule.

Configuration#

These rules are configured on the map service definition. For example:

<mapNodeService type="Uniform.Services.MapNodeService, Uniform.Content.Sitecore" singleInstance="true">  <!--   <excludeRules hint="raw:AddExcludeRule">                <home id="f1c51eb5-1828-4e46-8be8-09350bdcda5b" type="Uniform.ExcludeRules.ItemIdRule, Uniform.Content.Sitecore" />    </excludeRules>    --->
   <includeRules hint="raw:AddIncludeRule">     <home id="f1c51eb5-1828-4e46-8be8-09350bdcda5b" type="Uniform.ExcludeRules.ItemIdRule, Uniform.Content.Sitecore" />   </includeRules></mapNodeService>
Default rules#

The following rule types are provided with Uniform:

Field value rule

The item must have the specified field with the specified value to be included or excluded from the map.

Sample configuration:

<!-- using field name --><FieldByNameRule1 type="Uniform.ExcludeRules.FieldValueRule"                  field="Region"                         value="R01" />
<!-- or using field id --><FieldByNameRule2 type="Uniform.ExcludeRules.FieldValueRule"                  field="{9B7B968C-DF0D-4619-8837-B397BAE38E80}"                   value="R02"  />
  • where the field attribute must contain either a field id or a field name
  • where the value attribute must contain the string value of the field.

Item id rule

The item id must match the specified value to be included or excluded from the map.

Sample configuration:

<ItemIdRule1 type="Uniform.ExcludeRules.ItemIdRule"             id="{A2611FE7-A38E-42E3-A70B-77ECE7DCE14E}" />
  • where the id attribute must contain the item id

Item template id rule This rule interrogates the item's template id (by optionally checking the base template ids)

This rule is available in v4.0.1+

Sample configuration:

<ItemTemplateRule1 type="Uniform.ExcludeRules.ItemTemplateRule, Uniform.Content.Sitecore"                    templateId="{3844076F-382D-4B46-95BC-126C987FE0E4}"                   checkBaseTemplates="true" />
  • where the templateId attribute must contain the template id
  • where the boolean checkBaseTemplates attribute instructs whether to check base templates.
Custom rules#

Custom include/exclude rules can be created by implementing the interface Uniform.ExcludeRules.IIncludeExcludeRule.

Sample configuration:

<mapNodeService type="Uniform.Services.MapNodeService, Uniform.Content.Sitecore" singleInstance="true">    <excludeRules hint="raw:AddExcludeRule">        <home name="Home" type="Samples.ItemNameRule, Samples" />  </excludeRules> </mapNodeService>

Sample implementation:

namespace Samples{    public class ItemNameRule : IIncludeExcludeRule    {      public string ItemName { get; private set; }
      public void Init(XmlNode configNode)      {        var itemName = configNode.Attributes["name"]?.Value;        if (string.IsNullOrWhiteSpace(itemName))        {            throw new InvalidOperationException("Attribute name is missing");        }        this.ItemName = itemName;      }
      public bool Applies(Item item)      {        return item.Name.Equals(this.ItemName);      }    }}

Page service#

Page service returns page-level item fields, renderings + datasources as JSON as well as MVC rendering as html if present on the layout details.

Usage#

GET: /uniform/api/content/<site-configuration-name>/page/<pagepath>?uniform_token=<token>

where:

  • <site-configuration-name> is equal to the name of your site configuration site (e.g website). Learn more about Site Configuration here.
  • <pagepath> is equal to the path of the page starting from the home item of the given site (e.g. places/cities/nyc) or the Sitecore item ID (e.g. 40a0f258-b65d-4aed-b961-253cbe153e0f).
  • <token> is the value of the Uniform.API.Token setting set during Uniform Connector configuration

This service accepts the additional querystring parameter uniform_preview=true|false. Add ?uniform_preview=true to the request will have it execute go against Sitecore's master database, which is useful for debugging.

Examples#

For the "Home" page of the website site requested from the CM instance, this URI will be:

https://<sitecore-host>/uniform/api/content/website/page

For the "Contact Us" page, which is a child of the "Home" page, it will be: https://<sitecore-host>/uniform/api/content/website/page/contact-us or https://<sitecore-host/uniform/api/content/website/page/{A2ECFDD7-7380-4252-BF21-F002DF3A8C46}

Sample output#

Expected response of this service will contain all page renderings, datasources, fields, as well as tracking and personalization rules set if present. It also contains "mvc" part that has MVC render output of all the renderings assigned to the requested item.

Uniform Page Service Output

Render service#

This service may be instrumental when you want to issue a re-render of a Sitecore rendering from JavaScript (after login for example). By passing this request to the Sitecore origin server along with auth cookies and any additional custom query string parameters your rendering code may be dependent on, you are able to re-use the dynamic presentation layer functionality on statically exported pages. The result of this service is HTML that can be rendered by jQuery client-side or any other JS library for that matter.

Usage#

GET /uniform/api/content/<site-configuration-name>/render/<pageitemid>/<renderingid>?uniform_token=<token>

where:

  • <site-configuration-name> is equal to the name of your site configuration site (e.g website). Learn more about Site Configuration here.
  • <pageitemid> is equal to the Sitecore item ID for the page with the rendering (e.g. 40a0f258-b65d-4aed-b961-253cbe153e0f).
  • <renderingid> is equal to the Sitecore item ID for the rendering's definition item (NOTE: This is not the rendering's uid. If a rendering is used multiple times on a page, all instances of that rendering are included).
  • <token> is the value of the Uniform.API.Token setting set during Uniform Connector configuration

This service accepts the additional querystring parameter uniform_preview=true|false. Add ?uniform_preview=true to the request will have it execute go against Sitecore's master database, which is useful for debugging.

Examples#

Without parameters: https://<sitecore-host>/uniform/api/content/website/render/ff024edd-44fb-42ef-9ecd-1e8daf706386/a7ab411c-f894-4142-b069-48ef67431d36?token=12345

With parameters: https://<sitecore-host>/uniform/api/content/website/render/ff024edd-44fb-42ef-9ecd-1e8daf706386/a7ab411c-f894-4142-b069-48ef67431d36?token=12345&uniform_datasource=f39aa710-4231-45f8-a075-975bb41099a7

Sample output#

Expected response of this service is the rendered HTML for the rendering.

If an empty string is returned, this means the rendering failed. Additional information may be available in the Sitecore log. For example, if a data source that is incompatible with the rendering is specified, an empty string is returned. The Sitecore log includes an error like the following:

2572 19:32:58 ERROR Presentation error: Data source isn't set or have wrong template. Template {ABBAA00B-8CA7-4C9A-A5C1-156332590EE2} is required, Context item ID: {FF024EDD-44FB-42EF-9ECD-1E8DAF706386}, Rendering ID: {FF024EDD-44FB-42EF-9ECD-1E8DAF706386}

Build service hosted API endpoints#

These are service endpoints integrated into Next.js and Nuxt frameworks and allow to initiate builds and check for status.

Status service#

Status service provides information about the Uniform service.

Usage#

GET /uniform/api/service/status?uniform_token=<token>

where:

  • <token> is equal to the value of UNIFORM_API_TOKEN environment variable that in turn must match the value of the Uniform.API.Token configured on the Sitecore side.

Sample output#

{    "status": "ready",    "version": "unknown",    "appVersion": "4.0.0",    "appDescription": ""}