Using the RESTful API for the EntityService

Last updated Tuesday, August 30, 2016 in Sitecore Experience Platform for Developer
Keywords: Development

You use the EntityService to create custom controller classes on the server. These classes are accessible over HTTP.

Sitecore.Services.Infrastructure.Web.Http.DefaultRouteMapper provides a default route to access these custom controller classes. This route and a custom controller selector for the Web API are configured during the application startup of the website.

Default routing

A custom controller class that acts as an EntityService must be addressable through a unique URL. You fulfill this requirement by deriving the URL from the fully qualified type name of the custom controller class in question.

The route definition that applies to EntityService classes is:

{namespace}/{controller}/{id}/{action}

where:

  • id is an optional parameter.
  • action is the name of the method you want to invoke on the controller.

Mapping HTTP verbs

All EntityService endpoints respond to the following HTTP verbs:

  • GET – maps to the FetchEntity method (when id parameter is supplied) or to the FetchEntities method (when id parameter is not supplied) of the EntityService.
  • POST – maps to the CreateEntity method of the EntityService.
  • PUT – maps to the UpdateEntity method of the EntityService.
  • DELETE – maps to the Delete method of the EntityService.
  • OPTIONS – maps to the MetaData method of the EntityService.

Mapping type name to URL

Sitecore.Services.Client uses the full type name for the controller class to map incoming HTTP requests to EntityService endpoints by default.

The two route parameters that are the key to this process are {namespace} and {controller}. The non-optional part of the route definition is:

{namespace}/{controller}

where:

  • {namespace} is derived from the namespace of the class name, with "." characters converted to "-". characters.
  • {controller} is the class name without the Controller suffix. This follows the MVC convention for controller naming.

For example, the My.Namespace.ProductController qualified type name maps to the my-namespace/product URL.

Custom controller action routing

You can add custom action methods to an EntityService controller class. Sitecore.Services.Client automatically routes requests to the appropriate action method if you supply {id} and {action} parameters in the URL of the request.

This uses the {namespace}/{controller}/{id}/{action} route. The default routing configuration does not support a request that does not supply an {id} parameter (the {namespace}/{controller}/{action} route).

Configuration

The Sitecore.Services.Client.config include file contains the following configuration option:

Setting

Description

Sitecore.Services.RouteMapper

The Sitecore.Services.RouteMapper setting specifies the Sitecore.Services.Infrastructure.Web.Http.IMapRoutes derived type that configures routes for Sitecore.Services.Client.

The default value for this setting is Sitecore.Services.Infrastructure.Web.Http.DefaultRouteMapper, Sitecore.Services.Infrastructure.

Service endpoint stem

All EntityService controllers are located under a single URL: Sitecore/api/ssc/.

Override namespace routing

The ServicesControllerAttribute class provides a constructor that takes a UniqueName parameter. You use the UniqueName parameter to specify the {namespace} and {controller} route data values for a controller explicitly. You can override the default “type name to URL mapping mechanism” this way.

The following examples show how the UniqueName parameter value maps to a URL that will access a controller:

UniqueName

URL

product

product

company.product

company.product

company/product

company.product

long.company.product

long-company/product

long/company/product

long-company/product

long.company/product

long-company/product

A unique name that does not provide both the {namespace} and the {controller} parts is not serviced by the {namespace}/{controller}/{action} route, and can generate HTTP 404 responses.

For a high-level overview of routing, see Routing in ASP.NET Web API.