Return to blog

Sitecore Item Web API Client Library

Shared Source

The Sitecore Item Web API is an officially supported module released by Sitecore in November 2012. In its initial release the purpose of the module is to provide developers with programmatic access to a Sitecore instance so that items can be manipulated through code.

Sitecore's official explanation goes as follows... Developers use the Sitecore Item Web API to manipulate the content items in Sitecore through HTTP requests. The API gives access to content through items paths, IDs, and Sitecore queries. This service produces output in JSON format and is both highly customizable and optimised to support a minimum number of requests.

Most of us who have been working with Sitecore over the years will no doubt have written custom web services to support systems integrations using Sitecore as a central content repository so this module is a very welcome addition. To get my hands dirty with the module and understand its capabilities I decided to write a client library in C# so that

  1. I had an excuse to write code!
  2. My life would be easier if I have the need to 'talk' to the Item Web API from a .NET application outside of Sitecore
  3. I could share the code with all of you and hopefully get some feedback

I will point out at this point that the Item Web API supports multiple operation types read, create, delete etc. The first revision of the client library only supports read operations. I will be adding support for the additional operations over the next few weeks.

Update: the client now supports

  1. Read
  2. Create
  3. Update
  4. Delete

Installing the Sitecore Item Web API

Before I jump into the library and sample code I will point out a fairly obvious pre-requisite. You must have url access to a Sitecore instance that has the Item Web API installed. Installing the Item Web API is extremely straight forward

  1. Download the module from the Sitecore Developer Network
  2. The module is basically a Sitecore package, install it using the installation wizard
  3. Configure security by editing Sitecore.ItemWebApi.config, which can be found in {WebRoot}\App_Config\Include (NOTE: if you decide to use authentication the user must belong to the extranet domain and you must specify the fully qualified name in the username header)
  4. If you are using authentication and want to switch to the master database the user must belong to the Sitecore Client Users role

Library Examples

The key objects are:

  1. SitecoreDataContext
  2. AuthenticatedSitecoreDataContext
  3. SitecoreExpressionQuery
  4. SitecoreItemQuery
  5. SitecoreWebResponse
  6. WebApiItem
  7. WebApiField

Using these types (as demonstrated below) you will see how quickly you can get up and running and querying a remote Sitecore instance. The code is available to clone on github and comes with a demo project that covers typical scenarios.

Configuration

The library uses the popular log4net library to log requests, successes, failures etc. In order for this to function properly you need to tell the project where you plan to store the Config\SitecoreWebApiClient.config file. You can do this by simply editing the ConfigurationFilePath in the project settings

Anonymous Requests

To send an anonymous request we first have to create a new instance of SitecoreDataContext. By default it is assumed that the request will not be sent by SSL but you can pass an optional additional boolean parameter into the constructor of SitecoreDataContext to override the assumption

Now that we have a data context we can use it to send two types of queries

Expression Queries

Expression queries request items using Sitecore query

Item Queries

Item queries send a request for a specfic item using an item id

Sitecore Web Response

Now that we have a data context and a query we can pass the query into the GetResponse method of the data context to get a SitecoreWebResponse. A SitecoreWebResponse has properties that tell us about the status of the response and if successful the item data returned by the Sitecore Item Web API

Authenticated Requests

The two query examples above can also be used with an authenticated request. To do so instead of creating a new instance of SitecoreDataContext we create a new instance of AuthenticatedSitecoreDataContext, which expects a parameter of type SitecoreCredentials in it's constructor. You can optionally choose to send encrypted authentication headers

There are many more parameters that the Sitecore Item Web API allows us to specify and they are all supported by the item query types including

  • Database
  • Language
  • Fields
  • Payload
  • Scope
  • Paging

To try these options out download the code and experiment away! Once again this is currently read only, I will post updates on this blog when more operations become available.

Update: the client now supports

  1. Read
  2. Create
  3. Update
  4. Delete
Return to blog