Ratings

Note

These v4 APIs are now frozen. See the API versions available for details of the different API versions available. The only authentication method available at the moment is the internal one.

List ratings

This endpoint allows you to fetch ratings for a given add-on or user. Either addon or user query parameters are required, and they can be combined together.

When addon, user and version are passed on the same request, page_size will automatically be set to 1, since an user can only post one rating per version of a given add-on. This can be useful to find out if a user has already posted a rating for the current version of an add-on.

GET /api/v4/ratings/rating/
Query Parameters:

  • addon (string) – The add-on id, slug, or guid to fetch ratings from. When passed, the ratings shown will always be the latest posted by each user on this particular add-on (which means there should only be one rating per user in the results), unless the version parameter is also passed.

  • exclude_ratings (string) – Exclude ratings by their id. Multiple ratings can be specified, separated by comma(s).

  • filter (string) – The filter(s) to apply.

  • score (string) – Only include ratings that have been given a specific score. Multiple scores can be specified, separated by comma(s).

  • show_flags_for (string) – The user id to show flags for. If the request is made with an authenticated user matching this parameter value, a flags property will be added to the response as described below in ratings.

  • show_grouped_ratings (boolean) – Whether or not to show ratings aggregates for this add-on in the response (Use “true”/”1” as truthy values, “0”/”false” as falsy ones).

  • show_permissions_for (string) – The user id to show permissions for. If the request is made with an authenticated user matching this parameter value, and the addon parameter is also present, a can_reply property will be added to the response as described below.

  • user (int) – The user id to fetch ratings from.

  • version (int) – The version id to fetch ratings from.

  • page (int) – 1-based page number. Defaults to 1.

  • page_size (int) – Maximum number of results to return for the requested page. Defaults to 25.

Response JSON Object:

  • count (int) – The number of results for this query.

  • next (string) – The URL of the next page of results.

  • previous (string) – The URL of the previous page of results.

  • results (array) – An array of ratings.

  • can_reply (boolean) – Only present if the addon query parameter and show_permissions_for parameters are present. A boolean indicating if the user that made the ratings list request can reply to ratings in that list.

  • grouped_ratings (object) – Only present if show_grouped_ratings query parameter is present. An object with 5 key-value pairs, the keys representing each possible rating (Though a number, it has to be converted to a string because of the JSON formatting) and the values being the number of times the corresponding rating has been posted for this add-on, e.g. {"1": 4, "2": 8, "3": 15, "4": 16: "5": 23}.

By default, the rating list API will only return not-deleted ratings, and include ratings without text. You can change that with the filter query parameter. You can filter by multiple values, e.g. filter=with_deleted,without_empty_body,with_yours

Value

Description

with_deleted

Returns deleted ratings too. This requires the Addons:Edit permission.

without_empty_body

Excludes ratings that only contain a rating, and no textual content.

with_yours

Used in combination without_empty_body to include your own ratings, even if they have no text.

Detail

This endpoint allows you to fetch a rating by its id.

Note

Users with Addons:Edit permission will be able to see deleted ratings. Use the is_deleted property to distinguish those from normal ratings everyone is able to see.

GET /api/v4/ratings/rating/(int: id)/
Query Parameters:

  • show_flags_for (string) – The user id to show flags for. If the request is made with an authenticated user matching this parameter value, a flags property will be added to the response as described below.

Response JSON Object:

  • id (int) – The rating id.

  • addon (object) – A simplified add-on object that contains only a few properties: id, name, icon_url and slug.

  • body (string|null) – The text of the rating.

  • is_deleted (boolean) – Boolean indicating whether the rating has been deleted or not.

  • is_latest (boolean) – Boolean indicating whether the rating is the latest posted by the user on the same add-on.

  • previous_count (int) – The number of ratings posted by the user on the same add-on before this one.

  • flags[] (object) – A list of flags the user requesting has previously applied to this rating (that haven’t been processed by moderators already). Only present if show_flags_for parameter sent.

  • flags.flag (string) – A constant describing the reason behind the flagging.

  • flags.note (string|null) – A note to explain further the reason behind the flagging if flag was rating_flag_reason_other; null otherwise.

  • score (int) – The score the user gave as part of the rating.

  • reply (object|null) – The rating object containing the developer reply to this rating, if any (The fields rating, reply and version are omitted).

  • version.id (int) – The add-on version id the rating applies to.

  • version.version (string) – The add-on version string the rating applies to.

  • user (object) – Object holding information about the user who posted the rating.

  • user.id (string) – The user id.

  • user.name (string) – The user name.

  • user.url (string) – The user profile URL.

  • user.username (string) – The user username.

Post

This endpoint allows you to post a new rating for a given add-on and version. If successful a rating object is returned.

Note

Requires authentication.

POST /api/v4/ratings/rating/
Request JSON Object:

  • addon (string) – The add-on id the rating applies to (required).

  • body (string|null) – The text of the rating.

  • score (int) – The score the user wants to give as part of the rating (required).

  • version (int) – The add-on version id the rating applies to (required).

Edit

This endpoint allows you to edit an existing rating by its id. If successful a rating object is returned.

Note

Requires authentication and Addons:Edit permissions or the user account that posted the rating.

Only body and score are allowed for modification.

PATCH /api/v4/ratings/rating/(int: id)/
Request JSON Object:

  • body (string|null) – The text of the rating.

  • score (int) – The score the user wants to give as part of the rating.

Delete

This endpoint allows you to delete an existing rating by its id.

Note

Requires authentication and Addons:Edit permission or the user account that posted the rating. Even with the right permission, users can not delete a rating from somebody else if it was posted on an add-on they are listed as a developer of.

DELETE /api/v4/ratings/rating/(int: id)/

Reply

This endpoint allows you to reply to an existing user rating. If successful a rating reply object is returned - a rating object but with the fields rating, reply and version omitted.

Note

Requires authentication and either Addons:Edit permission or a user account listed as a developer of the add-on.

POST /api/v4/ratings/rating/(int: id)/reply/
Request JSON Object:

  • body (string) – The text of the reply (required).

Flag

This endpoint allows you to flag an existing user rating, to let a moderator know that something may be wrong with it.

Note

Requires authentication and a user account different from the one that posted the rating.

POST /api/v4/ratings/rating/(int: id)/flag/
Request JSON Object:

  • flag (string) – A constant describing the reason behind the flagging.

  • note (string|null) – A note to explain further the reason behind the flagging. This field is required if the flag is rating_flag_reason_other, and passing it will automatically change the flag to that value.

Response JSON Object:

  • object – If successful, an object with a msg property containing a success message. If not, an object indicating which fields contain errors.

Available constants for the flag property:

Constant

Description

rating_flag_reason_spam

Spam or otherwise non-rating content

rating_flag_reason_language

Inappropriate language/dialog

rating_flag_reason_bug_support

Misplaced bug report or support request

rating_flag_reason_other

Other (please specify)