Create a ServiceStack web service
While the out of the box Sitefinity CMS OData services provide the best option for quickly configuring a web service without writing any custom code, sometimes your scenario might require building additional functionality and integration. In such cases, Sitefinity CMS enables developers to easily create fast REST web services based on the ServiceStack framework which is included in your Sitefinity CMS project. Creating your own ServiceStack service with Sitefinity CMS is very straightforward – you need to define your request and response data transfer objects (DTO, specify your routes, implement your business logic, and finally register the service in Sitefinity CMS. This article demonstrates the process in detail.
Define your DTOs
Data transfer objects allow you to define the service input and output data format. This way you can control how the data, your web service works with, is sent over the network. Request and Response DTOs follow a naming convention, where the Response DTO class name should be like RequestDTOClassNameResponse. For example:
In the above sample we have defined a Request DTO that exposes a public GUID property. This way you require clients working with your service to pass a parameter of type GUID. In the matching Response DTO we have a public property of type string where the results of the service operation can be passed in a desired format. The Response DTO also includes a public property of type ResponseStatus , which facilitates the ServiceStack automatic exception handling.
Annotating your Request DTO with the IReturn<T> marker enables a generic typed API. This way you can use clients without having to know and specify the Response explicitly. If you don’t need to return a response you can simply annotate your Request DTO with the IReturnVoid marker.
You can define more than one Request and Response DTO for your web service and have each DTO handle specific operation.
Specify your routes
All ServiceStack services in Sitefinity CMS are made available under the /restapi endpoint. When you define the routes for your new web service, you expose the method names that will be available under /restapi. If you want to pass parameters when calling your web service, your routes can accept any public properties of the Request DTO objects. For example:
In the above sample we have defined a route called DeleteOrphanedUserProfile. This way clients can access your service at https://www.yoursitedomain.com/restapi/ DeleteOrphanedUserProfile. The route also exposes the public property UserId, meaning calls to your service for this route must pass a single parameter of type GUID. For example, https://www.yoursitedomain.com/restapi/ DeleteOrphanedUserProfile/2CC975E5-27A2-4275-8AEB-C3413D19FD67
You can define more than one route for your web service and have each route handle specific operation.
Implement your service
The service class is where you implement your business logic. In this class you add methods which determine what happens when clients call your routes. The service must inherit from the ServiceStack Service class or implement the IService interface. The method names in your service must follow a naming convention and match the respective HTTP Verb that you want your method to execute for. For example, a method name “Any”, means that the method can be called with Any HTTP Verb, while naming your method “Delete”, restricts this method only for the Delete HTTP Verb. Inside your methods you have access to the values of the Request DTO specified when calling your service routes. Once you’re done you can return a response via the defined Response DTO matching the Request your service method uses.
The following sample demonstrates a method which accepts any HTTP verb and works with the DeleteOrphanedUserProfilesRequest Request DTO described above:
Register your service
Implement the registration plugin
To make you new web service available for clients you first need to register it in Sitefinity CMS. This is done via implementing a plugin that registers your service in the ServiceStack host. To create a plugin, you must create a new class and implement the IPlugin interface. Implementing the interface requires you to have a Register method in your plugin, where you do the actual service registration. For example:
Register the plugin in Sitefinity CMS
Once you have your plugin ready, you need to make the Sitefinity CMS ServiceStack host aware of it. You do that by calling the RegisterServiceStackPlugin of Sitefinity CMS SystemManager. This should be done in your Global.asax by inside the Application_Start method. For example:
As a result, your service is registered with Sitefinity CMS and can be consumed by clients.