Entity Services

ivanbuzyka edited this page Sep 13, 2016 · 10 revisions

Implementing an Entity Service

UPDATE: at the time of writing of these wiki articles, the SSC documentation was finally published on doc website. Check out following articles related to Entity Services:

NOTE: there are some issues for turning on CORS for EntityService as it is described in the article mentioned above. Read more about that [here] (../wiki/Supporting-CORS)

Note 2: there is also a problem when using Sitecore JavaScript API for calling of EntityService. It is currently not possible (at least for Sitecore 8.1 Update-3) to share authentication cookie. Read more in [this wiki article] (../wiki/Authentication-cookie-sharing)

The actions to do

  1. Install a clean version of Sitecore 8.1.
  2. Clone this project and publish that in Visual Studio to Sitecore instance
  3. Take a look at the class TestEntityController that is inherited from EntityService<TestEntity>

it looks empty:

using System.Net.Http;
using System.Web.Http.Cors;
using Sitecore.Services.Core;
using Sitecore.Services.Infrastructure.Sitecore.Services;
using Sitecore.SSC.EntityServicesExammple.Models;
using Sitecore.SSC.EntityServicesExammple.Repositories;

namespace Sitecore.SSC.EntityServicesExammple.Controllers
{
    [ServicesController]
    public class TestEntityController : EntityService<TestEntity>
    {
        public TestEntityController() : this(new TestEntityRepository())
        {
        }

        public TestEntityController(IRepository<TestEntity> repository) : base(repository)
        {
        }

    }
}

But that inheritance from EntityService<TestEntity> do the job for us. Explore TestEntityRepository and the methods implemented there. You don't need to take care of routes in this case in order to request Entity Service. Sitecore will use own routing agreement.

So in order to request that service (for example GetAll() method) you need to do something like this:
GET http://your-host-name/sitecore/api/ssc/Sitecore-SSC-EntityServicesExammple-Controllers/TestEntity

What we see after sitecore/api/ssc/ path there is namespace and controller name of TestEntityController class (without 'controller' suffix). The dots ('.') should be exchanged by dash '-' character.

So as a response you'll get following json (just the collection of that TestEntity objects hard-coded in the repository):

[
  {
    "Title": "Title 1",
    "Text": "sitecore\\admin is current user",
    "Id": "a75b508b-a21a-4052-9578-3216ccdb7226",
    "Url": "http://sc81server/sitecore/api/ssc/Sitecore-SSC-EntityServicesExammple-Controllers/TestEntity/a75b508b-a21a-4052-9578-3216ccdb7226"
  },
  {
    "Title": "Title 2",
    "Text": "web is current DB name",
    "Id": "e1136893-ac44-48bf-b522-5cd0f0492fa2",
    "Url": "http://sc81server/sitecore/api/ssc/Sitecore-SSC-EntityServicesExammple-Controllers/TestEntity/e1136893-ac44-48bf-b522-5cd0f0492fa2"
  }
]

What about CRUD operations?

Theoretically, all the CRUD operations should be already supported, what you need to do is to implement the methods in repository correctly.
For example method Delete(TestEntity entity) in TestEntityRepository will be executed as soon as you do the following call:
DELETE http://your-host-name/sitecore/api/ssc/Sitecore-SSC-EntityServicesExammple-Controllers/TestEntity/e1136893-ac44-48bf-b522-5cd0f0492fa2. ID is the ID of the object that should be removed from the repository.

Yet another way to do Services: "ServicesApiController"

There is one more option how to create custom web services (I would say Entity Services, but not sure whether it is right name here since it is something different but not Entity Services). You can create your own ApiController that should be inherited from Sitecore's ServicesApiController. In this case, you need to take care of registering of an appropriate route in order to be able to call that controller by URL.

See an example in this project: the class ExampleServiceController and the class RegisterHttpRoutes that registers appropriate route. That route registration happens in the initialize pipeline:

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <pipelines>
      <initialize>
        <processor patch:after="processor[@type='Sitecore.Pipelines.Loader.EnsureAnonymousUsers, Sitecore.Kernel']"
          type="Sitecore.SSC.EntityServicesExammple.Pipelines.RegisterHttpRoutes, Sitecore.SSC.EntityServicesExammple" />
      </initialize>
    </pipelines>
  </sitecore>
</configuration>

So, let's do a request from Postman:

GET http://your-host-name/sitecore/api/exampleservice/

You'll get json content in the response.

Note: Be careful if you plan to create some custom "global" authorization filters for such controllers that are inherited from "ServicesApiController", Sitecore functionality contains also some, so you may break Sitecore them.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.