Wiki source code of new API for Ratings
Last modified by Vincent Massol on 2024/02/26 17:55
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
3.1 | 1 | {{box cssClass="floatinginfobox"}} |
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | A Rating API is available since XWiki 6.4 (see [[Rating API>>extensions:Extension.Ratings API]]), however this API suffers from several drawbacks: | ||
| 6 | |||
| 7 | 1. the API has been conceived to consider that the Ratings will be stored as xobjects: this is a bad design choice, the API should be agnostic about the way Ratings are stored, especially since storing data as xobject is not scalable | ||
| |
1.1 | 8 | 2. a big part of the API is exposed and not internalized: this makes it difficult to evolve without breaking backward compatibility |
| 9 | 3. the API is entirely dedicated for Ratings of Page and currently only one instance of Rating can exist in a wiki, however there could be needs to allow in the same wiki ratings of Pages, Comments, custom XObjects, etc. | ||
| 10 | |||
| 11 | Moreover, until now the Rating app wasn't bundled in XWiki Standard, but it changes with the creation of Likes which now relies on the Ratings API. This also pushed for new needs, which is why we start this work now. | ||
| 12 | |||
| |
3.1 | 13 | This design page aims at listing all the usecases we'd need for a Ratings API that could be used for various usages of Ratings (using it for Ratings pages, but also for Liking Page, comments, or Ratings comments, etc). |
| 14 | I will try in the following to provide information about what's already available and what is not. | ||
| |
1.1 | 15 | One goal of the page is to help decide if we need a completely new module for rating API and discard the old one, or if we can refactor the existing one. |
| 16 | |||
 |
5.1 | 17 | = Use-Cases = |
| |
1.1 | 18 | |
| |
1.2 | 19 | - UC1: Allow to handle multiple RatingsManager in an instance of XWiki with a dedicated scale for each one (e.g. a "RatingsPage" RatingsManager with a scale on 0 to 5, a "LikePage" RatingsManager with a scale on 0 to 1, etc) [not supported with original Rating API] |
| |
1.3 | 20 | - UC2: Allow to retrieve Ratings information for a specific RatingsManager instance with following information: entityreference rated, userreference who rates, actual note on the scale, date of rating, date of update of rating [partially supported: only for DocumentReference, without the update date and for one RatingManager] |
| 21 | - UC3: Allow to store a Rating vote for a specific RatingsManager on a dedicated EntityReference: scale must be respected [supported for one RatingManager] | ||
| 22 | - UC4: Allow to retrieve an average score of Ratings for a specific RatingsManager on a specific EntityReference: the average should be pre-computed for scalability reason [already supported for one RatingManager] | ||
| |
1.2 | 23 | - UC5: Allow to retrieve the full number of Ratings for a specific RatingsManager on a specific EntityReference: particularly useful when scale is [0,1] [not supported] |
| |
1.3 | 24 | - UC6: Allow to retrieve all Ratings of an user for a specific RatingsManager: query should be doable with pagination [supported for one RatingManager] |
| |
1.2 | 25 | - UC7: Allow to retrieve the Ratings based on a complex query on a specific RatingsManager: e.g. ratings of a user between 2 dates [not supported] |
| |
1.3 | 26 | - UC8: Send events when a Ratings is created / updated / deleted [only supported for update and for one RatingManager] |
| 27 | - UC9: Allow to provide different storages for Ratings: e.g. Solr, Hibernate Mapping, etc [supported for storing as xobjects and in Solr and for one RatingManager] | ||
| 28 | - UC10: Manage Ratings Rights for each instance of RatingsManager [not supported] | ||
| 29 | - UC11: Compute a Users' reputation based on their vote and on the vote of the pages they authored [supported] | ||
| 30 | - UC12: Allow to handle CRUD operations of a specific RatingsManager through a script service [supported only for one RatingManager] | ||
| |
1.4 | 31 | - UC13: It should be possible to migrate old Ratings information |
| |
4.1 | 32 | - UC14: Extension Repository should work with this new API |
| |
6.1 | 33 | - UC15: Allow to import/export Ratings informations |
| 34 | - UC16: Supports handling Average Ratings as XObject | ||
| |
1.2 | 35 | |
| |
5.1 | 36 | == UC1: Allow to handle multiple RatingsManager in an instance of XWiki == |
| |
1.3 | 37 | |
| 38 | This use case is about being able to create a new dedicated RatingManager for a specific purpose on XWiki just by calling a dedicated API. | ||
| 39 | This API should include: | ||
| 40 | - an identifier for the RatingManager instance | ||
| 41 | - the voting scale (e.g. [0,1] for a Like, [0,5] for actual Ratings) | ||
| |
3.1 | 42 | \\The API might also include: |
| |
1.4 | 43 | - the Type of EntityReference to be voted for: Not sure about that one, since it could limit further usages. |
| |
1.3 | 44 | |
| 45 | This is currently not supported in existing Rating application. | ||
| 46 | |||
| |
5.1 | 47 | == UC2: Allow to retrieve Ratings information for a specific RatingsManager == |
| |
1.3 | 48 | |
| 49 | For a given RatingManager instance, it should be possible to retrieve all Ratings with pagination for scalability. | ||
| 50 | Ratings information should be: | ||
| 51 | - EntityReference of the element being voted for | ||
| 52 | - UserReference of the user who performs the vote | ||
| 53 | - vote: an integer in the scale of the RatingManager instance | ||
| 54 | - createdDate: date of the first vote | ||
| 55 | - updatedDate: date of the latest update of the vote | ||
| 56 | - DocumentVersionReference: (if it applies) reference of the document reference version that contains the EntityReference | ||
| 57 | - RatingManager ID | ||
| 58 | - Rating ID | ||
| 59 | - RatingManager scale | ||
| 60 | |||
| 61 | This is partially supported: not all information are available, the types are currently wrong (e.g. a DocumentReference is stored instead of an EntityReference) and it's only supported for one RatingManager. | ||
| 62 | |||
| |
5.1 | 63 | == UC3: Allow to store a Rating vote for a specific RatingsManager on a dedicated EntityReference == |
| |
1.3 | 64 | |
| |
1.4 | 65 | A given user should be able to vote for an EntityReference and store it using a specific RatingsManager instance. |
| |
3.1 | 66 | If the user already voted for this EntityReference on the same RatingsManager instance, then his vote should be updated. |
| |
1.4 | 67 | Note that maybe in the future we'd need a configuration to prevent updating a vote. |
| |
1.3 | 68 | |
| |
1.4 | 69 | For some usecases (e.g. like) we can also have a configuration to simply delete the vote if it's set to the lower bound (0 for Like) (cf. UC5). |
| |
1.3 | 70 | |
| |
1.4 | 71 | This is partially supported: only for rating a DocumentReference and on one RatingsManager. |
| |
1.3 | 72 | |
| |
5.1 | 73 | == UC4: Allow to retrieve an average score of Ratings for a specific RatingsManager on a specific EntityReference == |
| |
1.3 | 74 | |
| |
1.4 | 75 | It should be possible to compute for any EntityReference an average score of votes. |
| 76 | For scalability reason, this average score should be computed at each vote and stored permanently. | ||
| 77 | |||
| 78 | The average score result should display information about its computation, basically we should obtain: | ||
| 79 | - the average score computed (a double with all digits, not rounded) | ||
| 80 | - the total number of ratings taken into accounts | ||
| 81 | - the actual scale of the RatingsManager | ||
| 82 | - the RatingsManager ID | ||
| 83 | - the EntityReference | ||
| 84 | - the hint of the method use to compute the average score (see below) | ||
| 85 | |||
| 86 | Note that in the Actual Rating API it's also possible to compute an Average Rating balanced by the reputation of the Author. (See UC11). | ||
| 87 | |||
| |
5.1 | 88 | == UC5: Allow to retrieve the full number of Ratings for a specific RatingsManager on a specific EntityReference == |
| |
1.4 | 89 | |
| 90 | The idea here is to be able to have a count of all votes made for an EntityReference on a specific RatingsManager. | ||
| 91 | It could be particularly useful in case of Likes for example, when the Average rating doesn't really make any sense: in that case we'd want the total number of Likes, so the total number of votes if we consider that unlike is deleting the vote, and not putting the vote to 0. | ||
| 92 | |||
| 93 | Note that it could also be just the possibility to retrieve a count of Ratings matching some criteria (cf UC7). | ||
| 94 | |||
| 95 | This is not really supported right now. | ||
| 96 | |||
| |
5.1 | 97 | == UC6: Allow to retrieve all Ratings of an user for a specific RatingsManager == |
| |
1.4 | 98 | |
| |
3.1 | 99 | This can be seen as a specialization of UC7, but I wanted to have it since it's a really common UC. |
| |
1.4 | 100 | The idea is just to be able to retrieve all votes a user has made for a specific RatingsManager (e.g. all Likes, all Rating pages, etc). |
| 101 | |||
| 102 | Information should be retrieved with pagination for scalability reason. | ||
| 103 | |||
| |
5.1 | 104 | == UC7: Allow to retrieve the Ratings based on a complex query on a specific RatingsManager == |
| |
1.4 | 105 | |
| 106 | The idea here is to allow developers to be able to perform complex queries on Ratings based on the stored information. | ||
| 107 | Use cases we could imagine for those queries: | ||
| 108 | - being able to retrieve all Ratings of an user between 2 dates | ||
| 109 | - being able to retrieve all Ratings made for a specific version of a page | ||
| 110 | - being able to retrieve all Ratings above a given threshold | ||
| 111 | etc | ||
| 112 | |||
| 113 | The only evolving design I can think of right now for this, to avoid having something too complex, is an API with a Map of parameters. | ||
| 114 | |||
| 115 | This is currently not supported. | ||
| 116 | |||
| |
5.1 | 117 | == UC8: Send events when a Ratings is created / updated / deleted == |
| |
1.4 | 118 | |
| |
3.1 | 119 | Whenever a Ratings if created / updated / deleted an event should be send with the Rating information and the RatingsManager identifier. |
| |
1.4 | 120 | Two usecases already exist for those events: |
| 121 | - update of Average ratings | ||
| 122 | - send a user notification | ||
| 123 | |||
| 124 | This is only suppored for updating Ratings right now, and only for one RatingManager. | ||
| 125 | |||
| |
5.1 | 126 | == UC9: Allow to provide different storages for Ratings: e.g. Solr, Hibernate Mapping, etc == |
| |
1.4 | 127 | |
| 128 | The way Ratings are stored can evolve over time, so we should be able to provide different storages for Ratings. | ||
| |
3.1 | 129 | In the current implementation Ratings can be stored as XObjects or in Solr. |
| |
1.4 | 130 | I propose to drop support of Ratings as XObjects since it's not scalable, but instead to allow storing in Hibernate with a dedicated mapping. |
| 131 | |||
| 132 | The question of chosing the Storage manager for ratings is open: | ||
| 133 | - it could be an implementation choice only (e.g. using the component for Solr storage in Like implem) | ||
| 134 | - or it could be an Admin choice with a configuration, in which case this configuration could be for any RatingManager instance or for a dedicated one (e.g. storing in Solr for Like and in Hibernate for Ratings) | ||
| 135 | |||
| 136 | Moreover, does this change apply at runtime or does it need a restart? And what about allowing a Migration of data between 2 stores? | ||
| 137 | |||
| 138 | Right now this is supported in current implementation with a choice to be made by Admin. It's possible to change the Store at runtime, but there's no migration proposed. | ||
| 139 | |||
| |
5.1 | 140 | == UC10: Manage Ratings Rights for each instance of RatingsManager == |
| |
1.4 | 141 | |
| 142 | Performing a Rating on an element might be subject of a dedicated Right. This is the case for Like for example, where we have a dedicated Right for it. | ||
| 143 | We can imagine that any RatingsManager instance could have its associated Right, or that we manage globally Rating rights. | ||
| 144 | |||
| 145 | This is currently not supported by Rating API. | ||
| 146 | |||
| |
5.1 | 147 | == UC11: Compute a Users' reputation based on their vote and on the vote of the pages they authored == |
| |
1.4 | 148 | |
| |
1.5 | 149 | Current Rating implementation allows to compute a Score about a User: |
| 150 | - he gains points when performing a vote | ||
| 151 | - he gains points when being voted for | ||
| |
1.4 | 152 | |
| |
1.5 | 153 | From what I understand this reputation is mainly used to ponderate the Average Score. |
| 154 | I'm actually not sure if we really need such UC, from what I see it's available in Ratings API but not directly used in Ratings application. | ||
| 155 | |||
| |
5.1 | 156 | == UC12: Allow to handle CRUD operations of a specific RatingsManager through a script service == |
| |
1.5 | 157 | |
| |
3.1 | 158 | The main purpose of the Rating API is to be used in XWiki UI, so we'd need to be able to handle all CRUD operations on Ratings (and most of the API presented here) in a Script service just by specifying the identifier of the RatingsManager to use. |
| |
2.1 | 159 | |
| |
5.1 | 160 | == UC13: It should be possible to migrate old Ratings information == |
| |
3.1 | 161 | |
| 162 | This design pages is about proposing a new API for Ratings, so we should provide a way for migration the old Ratings information to be used in the new API. | ||
| |
4.1 | 163 | |
| |
5.1 | 164 | == UC14: Extension Repository should work with this new API == |
| |
4.1 | 165 | |
| 166 | The Extension Repository apparently works in few places directly with the old Ratings XClasses, we need to ensure to refactor it so it works directly with the new API. | ||
| |
6.1 | 167 | |
| 168 | == UC15: Allow to import/export Ratings information == | ||
| 169 | |||
| 170 | We should be able to export a set of ratings information and to reimport them in a new wiki without needing to move an entire Solr core. | ||
| 171 | |||
| 172 | == UC16: Supports handling Average Ratings as XObject == | ||
| 173 | |||
| 174 | Some other extensions are directly using Average Ratings XObjects to provide augmented information in search etc: we should allow to keep using xobject for Average Ratings for those usecases. |
