Creating Your Own Sitecore Services Client API Controllers

So now that I have my Sitecore Speak 3 Application there are multiple ways you can communicate with it. One way is to use the Sitecore Services Client API.

Sitecore provides a very useful Item Service that is useful to read information about items. The basic usage is something like this:

• To get an item given its id you would do something like this:
  
  http://{your sitecore url}/sitecore/api/ssc/item/110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9
• To get an item by path you can do something like this:
  
  http://{your sitecore url}/api/ssc/item/?path=/sitecore/content/Home
• To perform an item search you can do this:
  
  http://{your sitecore url}/api/ssc/item/search?term=Home

You can extend the Item Service to do more things.  David Peterson has written a good article to help you with this.

In my case, I needed something a bit different. I am getting some data from Sitecore items but additionally calling other APIs and pulling data from SQL Server and other sources.  For that it makes sense to create your own Controllers. 

Step 1: Create your Class Library

When doing this be aware of your version of Sitecore as you will need to make sure you are using the same version of the .NET Framework for your project.  I am using Sitecore 9.1 so I used 4.6.1 for my library.  I tried to use .NET Core or .NET Standard and it would not work for me.  When naming your take into account the routing.  By default it uses this as the route:

        http://localhost/api/ssc/{namespace}/{controller_name}/{id}/{controller_menhod}

        eg. http://localhost/api/ssc/SitecoreGuild-Ssc/Mentoring/123/GetTopics

WARNING: The namespace is important as Sitecore will use it for the default routing. You can override the routing with some more work but for me I tried to keep it simple and simplified my namespace name. This article provides more info on creating custom routes.

Next add the proper references to your .NET Framework 4.6.1 class library project in my case it is these:

•  Microsoft.AspNet.WebApi.Core v5.2.6 - If you are using 9.1 then you need to use this. There is a newer version but you will get issues as Sitecore uses this version.
• Sitecore.Services.Core - This would be the version in your bin folder after your Sitecore install.
• Sitecore.Services.Infrastructure - This would be the version in your bin folder after your Sitecore install.

Before you start your development, you can do a sanity check in your environment to see if that works. I used the Mike Robbins Controller in my .Net Framework project and copied the result to the bin folder. Once I saw that one was coming up I knew my project was configured correctly.  After that I deleted his controller and started on my own.  

Create a new controller and derive it from ServicesApiController. At the top make sure you include

using System.Web.Http;

If you do not then it will prompt you to include the MVC one and if you do that you will get lots of funky errors. This one step will save you lots of confusion later.

Once you are ready to go beyond localhost you will need to do some additional configurations which are mentioned in this article.

On your new controller you will probably want to include a name. If you don't then Sitecore will do it for you and it will likely not look pretty.

    [ServicesController("MyServices/MyController")]
    public class MyControllerServiceApiController : ServicesApiController

As you add actions to your controller you will need to decorate them with an action name.

        [ActionName("GetSample")]

        public string GetSample(string id)

        {

             return "MySample:

        }

If you forget to put action it may work for your first method or it may fail but if you have 2 methods the second one will definitely fail with: 

No action was found on the controller 'MyControllerServiceApiController' that matches the request."}