Sitefinity CMS provides a fully exposed web service API. The Sitefinity CMS webservice API is made of RESTful webservices, meaning that the design is following the principles outline by Roy Fielding in his doctoral dissertation.
There are two main approaches to webservices: SOAP and REST: Whereas SOAP based webservices expose methods (such as GetNewsItems or SaveNewsItem), REST works with resources as the cornerstones of its architecture and relies on the HTTP methods to provide the operational context.
Let us take a look at the following diagram comparing the two approaches.
In essence, with both approaches we are providing the client of the service with the ability to accomplish the CRUD tasks , however, where SOAP is offering arbitrarily named methods as an API, REST is able to provide uniform API by combining the resource name with the well known standards of the HTTP protocol.
Sitefinity CMS conventions
For every resource exposed through a webservice, Sitefinity CMS supports CRUD operations. Every call to a webservice supports an optional parameter for the provider name (Overview: Provider model ). If no provider name has been set through an optional query string parameter, default provider will be used.
When requesting a collection of resources, Sitefinity CMS supports also following optional parameters:
- sort - sort expression used to order the requested collection of items
- skip - number of items to skip before retrieving collection (used primarily for paging purposes)
- take - number of items to take when retrieving collection (used primarily for paging purposes)
- filter - filter expression in dynamic LINQ format used to filter the collection between it is returned to the client.
The primary key of the item to retrieve, create or update is always required and it is part of the web service path. When returning a collection of items, Sitefinity CMS will actually return a CollectionContext object which carries some additional information about the collection along with the actual collection of items.
All built-in webservices provided by Sitefinity CMS are located in the ~/Sitefinity/Services folder.
LocalizationResources web service exposes ResourceEntry objects to the clients of the web services. Starting from the version 4, Sitefinity CMS has built in localization mechanism which stores localizable resources as ResourceEntry objects. LocalizationResources webservice provides the way to work with this data through a webservice interface.
Every resource entry is identified by the three tokens which represent the primary key:
- CultureName - name of resources' culture (e.g. "en-US")
- ClassId - name of the class or group to which the resource belongs to (e.g. "Labels")
- Key - key of the resource by which it is identified inside of a class (e.g. "Cancel")
Example 1: Getting a single resource in JSON format Create a request to following address with the HTTP method GET:
/Sitefinity/Services/Localization/LocalizationResources.svc/en-US/Labels/Cancel
Example 2: Getting a single resource in XML format
Create a request to following address with the HTTP method GET: /Sitefinity/Services/Localization/LocalizationResources.svc/xml/en-US/Labels/Cancel
Example 3: Getting a single resource in JSON format for a specific provider
Create a request to following address with HTTP method GET: /Sitefinity/Services/Localization/LocalizationResources.svc/en-US/Labels/Cancel?provider=XmlResourceProvider
Example 4: Getting all resources in JSON format
Create a request to following address with HTTP method GET: /Sitefinity/Services/Localization/LocalizationResources.svc
Example 5: Getting all resources for a specific culture in JSON format
Create a request to following address with HTTP method GET: /Sitefinity/Services/Localization/LocalizationResources.svc/en-US
Example 6: Getting all resources of a single class for a specific culture
Create a request to following address with HTTP method GET: /Sitefinity/Services/Localization/LocalizationResources.svc/en-US/Labels
Example 7: Getting first 10 resources ordered by the last modified date which were modified in 2009
Create a request to following address with HTTP method GET: /Sitefinity/Services/Localization/LocalizationResources.svc/?sort="LastModified DESC"&skip=0&take=10&filter=LastModified > DateTime.Parse("1/1/2009")
NOTE: If you execute the GET request using a browser to that does not support URL encoding you need to encode the URL address manually.
Example 8: Create a new resource entry or update an existing one
Create a request to following address with HTTP method PUT and send an array of properties with which the new resource entry should be created or updated /Sitefinity/Services/Localization/LocalizationResources.svc/en-US/Labels/CustomLabel
Example 9: Delete a resource entry
Create a request to a following address with HTTP method DELETE /Sitefinity/Services/Localization/LocalizationResources.svc/en-US/Labels/Cancel
Notice the xml string before the culture name. All built-in Sitefinity CMS webservices will return response in XML format if the service path is prefixed by the xml token. By default, Sitefinity CMS will return results in JSON format.