HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket


In the Optimizely Community API, ratings and rating statistics are managed through a service implementing the `IRatingService` and `IRatingStatisticsService` interfaces, respectively. These services provide the ability to persist, retrieve, and remove ratings that you define and their associated rating statistics.

### Access an IRatingService

If the `Ratings` feature is installed to an Optimizely Content Management System (CMS) site via the feature's site integration package, get an instance of this service from the inversion of control (IoC) container.

Example:



If the feature is installed to a non-Optimizely CMS site, get an instance of a service from the default `factory` class provided in the package.

Example:



### Add a rating

Add a rating by using the `Add(Rating`) method of the `IRatingService`. This method accepts an instance of the `Rating` class and returns a reference to a new instance of that class, which has been populated with any additional, system-generated data (for example, a unique ID).



The service permits one rating per rater and target combination. If an attempt is made to add another rating for an existing rater and target combination, a `DuplicateRatingException` is thrown.

In the above example, the request to add a rating is invoked synchronously. An example of adding a rating asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



### Update a rating

To update a rating, which has been added through the platform, use the `Update(RatingId,RatingValue,RatingValue`) method of the `IRatingService`. This method accepts the ID of the rating to be updated (`RatingId`), the current value of the rating (`RatingValue`), and the new value of the rating to be set (`RatingValue`).

Note

This method accepts the current value of your `Rating`, in addition to the new value, to ensure consistency in the calculation of the statistical measures associated with that `Rating`.



If the rating to be updated does not exist or the specified current value is no longer consistent with the stored representation of that rating, a `RatingDoesNotExistException` is thrown.

If the identified rating is a Composite Rating, its value is updated, and its associated extension data remains intact. For information on Composite Ratings, see [Extending ratings with composites](🔗).

In the above example, the request to update a rating is invoked synchronously. An example of updating a rating asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



### Retrieve a rating

To retrieve a specific instance of a rating added through the platform, use the `Get(RatingId)` method of `IRatingService`. This method accepts an instance of the `RatingId` class, which identifies the rating to be retrieved. It returns the instance of the `Rating` class corresponding to that identifier.



If the requested rating cannot be found, a `RatingDoesNotExistException` is thrown.

In the above example, the request to retrieve a rating is invoked synchronously. An example of retrieving a rating asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



To retrieve a collection of ratings added through the platform, use the `Get(Criteria<RatingFilter>)` method. This method accepts an instance of `Criteria<RatingFilter>`, which contains the specifications necessary to retrieve the desired ratings.

The `Filter` property of the `Criteria<RatingFilter>` class accepts an instance of the `RatingFilter` class. This class contains specifications that let you refine the result set of ratings being retrieved. The `RatingFilter` properties include:

  • `Rater` – Assign a value (`Reference`) to this property to refine a result set to ratings contributed by the identified user.

  • `Target` – Assign a value (`IEnumerable<Reference>`) to this property refines a result set to ratings for the identified users or resources included in that collection.

You may apply the `RatingFilter` specifications in conjunction with one another. Each specification assigned a value in the filter further refines the result set (that is, a logical AND).

The example below demonstrates the retrieval of a result page of ratings that were contributed for a particular resource.



In the next example, a similar approach demonstrates the retrieval of a result page of ratings that were contributed by a particular user.



In the above examples, the request to retrieve ratings is invoked synchronously. An example of retrieving ratings asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



The `RatingSortFields` class exposes a set of fields upon which you can order a result set of ratings. You can apply these fields in the construction of sorting rules that you associate with your criteria. These fields include:

  • `RatingSortFields.Id`

  • `RatingSortFields.Created`

  • `RatingSortFields.Modified`

  • `RatingSortFields.Value`

  • `RatingSortFields.Rater`

  • `RatingSortFields.Target`

The example below shows how to apply sorting rules to order a result set by value, from highest to lowest. A fallback rule, subsequently ordering results with the same value by creation date (from newest to oldest), is also added.



For details on the use of criteria, including paging and sorting information, see _Criteria_ in [Discovering the platform](🔗).

### Remove a rating

To remove a specific instance of rating, which was previously added through the platform, use the `Remove(RatingId)` method. This method accepts an instance of the `RatingId` class, which identifies the `RatingId` to be removed. The result is the deletion of the rating corresponding to that ID.



In the above example, the request to remove a rating is invoked synchronously. An example of removing a rating asynchronously using the asynchronous overload with C#'s async and await keywords is described below.



### Access an IRatingStatisticsService

If the `Ratings` feature is installed to an Optimizely Content Management System (CMS) site via the feature's site integration package, get an instance of this service from the inversion of control (IoC) container.

Example:



If the feature is installed to a non-Optimizely CMS site, get an instance of a service from the default factory class provided in the package.

Example:



### Retrieve statistics

As ratings are added to and removed through the platform, simple statistics are automatically tabulated for targeted resources. You can retrieve the statistics to tabulate metrics for your rated resources. Within the platform, this information is represented with the `RatingStatistics` class.



The statistical information in this class includes:

  • `Target` – Reference to the resource to which the statistics apply.

  • `Sum` – The sum of all rating values attributed to the target resource.

  • `TotalCount` – The total count of all ratings attributed to the target resource.

  • `Mean` – The mean value of all ratings attributed to the target resource.

With this information, rating counts, sums, and averages may be tabulated within your application.

To retrieve a collection of `RatingStatistics`, use the `Get(Criteria<RatingStatisticsFilter>)` method of `IRatingService`. This method accepts an instance of the `Criteria<RatingStatisticsFilter>` class. This class contains specifications that let you refine the result set of rating statistics being retrieved. The `RatingStatisticsFilter` properties include:

  • `Targets` – Assigning a value (`IEnumerable<Reference>`) to this property refines a result set to rating statistics for the identified users or resouces included in that collection.



The `RatingStatisticsSortFields` class exposes a set of fields upon which you can order a result set of rating statistics. You can apply these fields in the construction of sorting rules that you associate with your criteria. These fields include:

  • `RatingStatisticsSortFields.Target`

  • `RatingStatisticsSortFields.TotalCount`

  • `RatingStatisticsSortFields.Sum`

  • `RatingStatisticsSortFields.Mean`

The example below shows how to apply sorting rules to order a result set by the `Sum` field of the `RatingStatistics` retrieved, from highest to lowest. A fallback rule, subsequently ordering results with the same value of the `Sum` field by target reference (in ascending order), is also added.



If an application has more sophisticated statistical needs, you can implement custom analyses by leveraging the paged retrieval of ratings available through the `Get(Criteria)` method of `IRatingStatisticsService`. Your application may interpret and tabulate those ratings according to its needs.

In the above example, the request to retrieve rating statistics is invoked synchronously. An example of retrieving rating statistics asynchronously using the asynchronous overload with C#'s async and await keywords is described below.