Using the RESTful API for the EntityService
Describes how to work with entities using the RESTful API.
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.
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
Controllersuffix. 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).
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 The default value for this setting is |
All EntityService controllers are located under a single URL: Sitecore/api/ssc/.
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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.