Headless development with Sitecore: Comparing Item Service and SXA JSON

VP, Technology and Solution Delivery

setembro 05, 2017

As we all know, Sitecore is pushing hard to improve the development experience in the headless scenario. While we await the next release and new features, there are at least two ways to facilitate headless development in Sitecore right now. In this post I’ll provide an overview of the Item Service and Sitecore Experience Accelerator (SXA) JSON, providing some thoughts on when each might be appropriate.

Option 1: Item Service

The ItemService is a long standing piece of the platform that provides a developer with a REST API to access Sitecore content for standard CRUD operations. By default, the ItemService endpoint requires authentication, so please check the documentation in the link above to set that up.

The major actions available are summarized below and the full description of parameters are in the referenced link.

Action HTTP verb

End Point (all start with /sitecore/api/ssc/)

Login POST


Logout POST


Read GET


Create POST  





Run a stored query GET


Run a search GET


Run a stored search GET


Let’s pause here. As you can see from the above list of actions, the ItemService is about data, but if your data it is in Sitecore you can probably get to it from the ItemService. Any presentation logic will be the developer’s complete responsibility.

Sitecore’s built-in data caching will apply inside the ItemService for reads, so do keep in mind that any updates triggered by your DELETE/UPDATE/CREATE may not be immediately visible to a read depending on what database you are acting against.

With this approach you also lose any capabilities inherited in the Experience Platform for personalization, testing and tracking. Now, if the above limitations are not a concern for your application, let’s continue.

Getting Data from Sitecore

We can pull the most commonly needed data from an item – in this case the default home item - with all content fields using the following endpoint call.


The resulting JSON looks like the following:






   "TemplateName":"Sample Item",









   "Text":"<p style=\"line-height: 22px;\">From a single connected platform that also integrates with other customer-facing platforms, to a single view of the customer in a big data marketing repository, to completely eliminating much of the complexity that has previously held marketers back, the latest version of Sitecore makes customer experience highly achievable. Learn how the latest version of Sitecore gives marketers the complete data, integrated tools, and automation capabilities to engage customers throughout an iterative lifecycle &ndash; the technology foundation absolutely necessary to win customers for life.</p>\n<p>For further information, please go to the <a href=\"\" target=\"_blank\" title=\"Sitecore Documentation site\">Sitecore Documentation site</a></p>",

   "Title":"Sitecore Experience Platform"


As you can see the response is quite easy to process with the one caveat that link expansion does not occur as a part of the ItemService. Sitecore handles this link expansion in the presentation layer, in particular the field renderers. So, if you have RichText fields you will need to keep this in mind.

Searches and Queries

For those of you that may want to run more complex retrieval operations, the search and query endpoints can be very helpful, especially the search as it lets you limit results on facets.

You can store and run preset queries or searches. The ItemService includes templates at /sitecore/templates/System/Services/Item Service that allow you to store queries and searches.

Query Example

The {id} in the following call being the GUID of your stored query you can retrieve a list of children of home.


The stored query item is created from template /System/Services/Item Service/Query/Query Definition. This allows you to store the Sitecore query and database like so:

Headless dev - ONE.png

The result of running the above is:








         "ItemName":"Query Folder",

         "ItemPath":"/sitecore/content/Home/Query Folder",



         "TemplateName":"Query Folder",




         "DisplayName":"Query Folder",








         "ItemName":"Search Folder",

         "ItemPath":"/sitecore/content/Home/Search Folder",



         "TemplateName":"Search Folder",




         "DisplayName":"Search Folder",








Search Example

The stored search call:


References a Sitecore item based on the template /System/Services/Item Service/Search/Query Definition. This allows you to store database, language, sorting and field settings like so. Note that on field sorting a “a” before the fieldname is ascending and “d” is descending.

Note: the term parameter is required in the call. You can pass a * if desired.

The below screen shot expressed in plain English is search the web database for items with templates of “folder” in the English language and order them by template name ascending then itemid descending. Return only the ItemId, ItemName, TemplateName fields.

Headless dev - TWO.png

The response:






               "Name":"sample item",




                  "Rel":"_templatename|sample item",




















Option 2: SXA JSON

In spring of 2017 Sitecore introduced a feature they termed data modelling to SXA. This feature is comprised of a specialized device, layout and renderings that output any SXA content in a JSON format. As the presentation layer of Sitecore is used to render the JSON you can access the resulting JSON through a simple URL pattern.

Query Description


Returns the JSON for the page at /home


Returns a rendering based on a placeholder.


Returns renderings with the ID content and spot1 from the /home page.


Returns renderings of type richtext from the /home page.


Returns renderings of type richtext in placeholder content from the /home page.


As the presentation engine is responsible for the JSON rendering the caveats about link expansion and output caching found in the item service are no longer applicable. Personalization and tracking of xDB would also still apply and you can define your own SXA rendering variants to further customize the JSON.

One thing not immediately clear (at least to me) from the documentation is that if you do not add any explicit JSON components to the JSON device, SXA is still capable of outputting most of the contents of the page.

Taking a blank SXA site and adding an image component to the page in the default device, the JSON response for this page at http://<hostname>/?sc_device=json included the fields of the page as well as those for the image component.







      "Content":"<p>Grants home page 12</p>",


















      "Body Id":"",







      "Page Design":"",


      "Body Css Class":"",



















This will meet the needs of many SPA’s and other client application. If you need more then you can define variants of the built-in JSON controls. This is already explained by Sitecore in the documentation.


To summarize, the ItemService and SXA provide different approaches to headless support. If you are using SXA just keep in mind that this is not an either or and you can combine SXA and ItemService if it makes sense.

  Item Service


CRUD Operations

Full CRUD Read only

Caching Layer


Data, Output (HTML/JSON)

Control of JSON Format


Can customize JSON components

Access to Sitecore Presentation Layer

No Yes

Support for Personalization

No Yes

Support for Tracking

No Yes

Support for AB/MV Testing

No In theory, but tricky

Implication for Authors


May need to manually build up the JSON layout in Experience Editor

Enfrente os desafios da economia digital de hoje

Pronto para dar o primeiro passo e aumentar o seu potencial digital? Entre em contato com a Valtech hoje.
Fale conosco