Why you should care about the Item Web API
There are many great articles and videos about using the Sitecore Web API, many of which are much more complete and sophisticated than this post (for particularly impressive skill, see Mike Reynolds's work). In this post I simply wanted to point out the basics and explain why you might be interested in this Sitecore feature (and, really, why you should be confident in the power of the Sitecore API in general). So read on as a non-developer. As a developer, you'll at least get a couple quick lines of code that might save you some time as you dive into things.The Sitecore Item Web API documentation may be found here. The latest version is 1.2, and the feature is now part of the core Sitecore install (as of 7.1). The basic premise of this feature is to expose the Sitecore API to modern, RESTful web service calls, to return JSON responses, and (as is always a core tenet to Sitecore) to provide an extensible basis for modeling virtually any business and technical requirements.
In plainer English, this makes Sitecore-curated content available outside of Sitecore sites. It allows you to ensure all of your content policies are followed (workflow, validation, security, publishing) before making that content available to additional groups or applications. Sitecore-Content-As-A-Service. (Feel free to use SCAAS and sound cool). By providing a modern RESTful service layer, it makes your developers happy and allows them to use all the productivity tools they are using today.
To consider a very simple use case, I'll use our team's Launch Sitecore project and consider an area of content that I'd like to make available to an external application. The "Team" section on the site lists all of our N. American Sales Engineers:
Setting up the scenario
Let's say that we're starting a separate project and we want to start by leveraging this list of SE's. Maybe we consider Launch Sitecore to be the place where we first add new SEs once hired and where we have some additional statistics and information about the SEs (# of articles written, favorite quote, etc.). By defining Sitecore as the system of record for this content, it frees us from worrying about content governance and consistency.
To keep things really simple, I tried to include as few lines as possible to accomplish this via the Sitecore Item Web API. First, the final result of the new application page:
 |
| A simple list of Sitecore content items (without that pesky styling getting in the way!) |
Next, the HTML behind the page
<!doctype html>
<html ng-app>
<head>
<title>List of Sales Engineers</title>
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.2.14/angular.js"></script>
<script src="../js/myangular.js"></script>
</head>
<body>
<div ng-controller="CallWebApi">
<ul>
<li ng:repeat="item in
data.result.items">{{item.DisplayName}}</li>
</ul>
</div>
</body>
</html>
- I'm using angular.js to allow the javascript library to do all the heavy lifting. The first script reference is to that library as hosted on Google's CDN. The second is simply my project's local javacript file that we'll look at.
- All of the "ng-" stuff is standard angular.js usage. The ng-controller will call out to my local javascript method that we'll discuss below. The ng:repeat will allow me to iterate through all Sitecore items I receive back from my web service call, showing each item's DisplayName field in a bullet list.
- Take special note of the "data.result.items" syntax above. The bulk of time you'll spend (probably with any JSON parsing exercise) is figuring out how to pull out the specific nodes and fields you are interested in.
The javascript to make the call and return the Sitecore items:
function CallWebApi($scope, $http) {
$http.get('http://mvc71/-/item/v1/?scope=s&query=/sitecore/content/home/team/*').
success(function (data) {
$scope.data = data;
console.log('success ' + data)
})
.error(function(data) {
console.log('failure ' + data)
});
The document on SDN does a great job explaining the possible operations and queries that you can make with the Item Web API. For now, consider that you can do things like:
- Get Sitecore Items
- Create Sitecore Items
- Create Media Library Items
- Change Items
- Get back the HTML output of a rendering
For this scenario, we're simply getting some Sitecore items and using their fields. The query above makes a request to Sitecore to get back all the items in the "Team" area of our Launch Sitecore content tree. In my case, that result becomes available to my angular.js within my page to list out DisplayNames for the Sales Engineers. Below is the structure of the JSON that we receive back from the request:
In Summary
While this is a very modest use case, this really provides the foundation for incredible real-world use cases within your organization. With Sitecore as the content hub, you are able to ensure your content-as-a-service project is fully governed. Your mobile apps and sites will benefit from the "create once, use everywhere, maintain once" pattern this promotes.
The Item Web API is fully extensible and built on the same core pipeline architecture that drives everything in Sitecore. Because of this, additional features and methods are able to be easily added to the standard set, and virtually any external application content need may be serviced by Sitecore.
