Reviews¶
Warning
These v3 APIs are now deprecated and you should switch to a newer version before it is removed. See the API versions available for details of the different API versions available and the deprecation timeline.
Note
The only authentication method available at the moment is the internal one.
List reviews¶
This endpoint allows you to fetch reviews 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 review per version of a given add-on. This can be useful to find out if a
user has already posted a review for the current version of an add-on.
- GET /api/v3/reviews/review/¶
- Query Parameters:
addon (string) – The add-on id, slug, or guid to fetch reviews from. When passed, the reviews shown will always be the latest posted by each user on this particular add-on (which means there should only be one review per user in the results), unless the
version
parameter is also passed.filter (string) – The filter(s) to apply.
user (string) – The user id to fetch reviews from.
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).
version (string) – The version id to fetch reviews 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 reviews.
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 review list API will only return not-deleted reviews, and include reviews 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 reviews too. This requires the Addons:Edit permission.
without_empty_body
Excludes reviews that only contain a rating, and no textual content.
with_yours
Used in combination without_empty_body to include your own reviews, even if they have no text.
Detail¶
This endpoint allows you to fetch a review by its id.
- GET /api/v3/reviews/review/(int: id)/¶
- Response JSON Object:
id (int) – The review id.
addon (object) – An object included for convenience that contains only two properties:
id
andslug
, corresponding to the add-on id and slug.body (string|null) – The text of the review.
is_latest (boolean) – Boolean indicating whether the review is the latest posted by the user on the same add-on.
previous_count (int) – The number of reviews posted by the user on the same add-on before this one.
rating (int) – The rating the user gave as part of the review.
reply (object|null) – The review object containing the developer reply to this review, if any (The fields
rating
,reply
andversion
are omitted).title (string|null) – The title of the review.
version.id (int) – The add-on version id the review applies to.
version.version (string) – The add-on version string the review applies to.
user (object) – Object holding information about the user who posted the review.
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 review for a given add-on and version. If successful a review object is returned.
Note
Requires authentication.
- POST /api/v3/reviews/review/¶
- Request JSON Object:
addon (string) – The add-on id the review applies to (required).
body (string|null) – The text of the review.
title (string|null) – The title of the review.
rating (int) – The rating the user wants to give as part of the review (required).
version (int) – The add-on version id the review applies to (required).
Edit¶
This endpoint allows you to edit an existing review by its id. If successful a review object is returned.
Note
Requires authentication and Addons:Edit permissions or the user account that posted the review.
Only body, title and rating are allowed for modification.
- PATCH /api/v3/reviews/review/(int: id)/¶
- Request JSON Object:
body (string|null) – The text of the review.
title (string|null) – The title of the review.
rating (int) – The rating the user wants to give as part of the review.
Delete¶
This endpoint allows you to delete an existing review by its id.
Note
Requires authentication and Addons:Edit permission or the user account that posted the review. Even with the right permission, users can not delete a review from somebody else if it was posted on an add-on they are listed as a developer of.
- DELETE /api/v3/reviews/review/(int: id)/¶
Reply¶
This endpoint allows you to reply to an existing user review. If successful a review reply object is returned.
Note
Requires authentication and either Addons:Edit permission or a user account listed as a developer of the add-on.
- POST /api/v3/reviews/review/(int: id)/reply/¶
- Request JSON Object:
body (string) – The text of the reply (required).
title (string|null) – The title of the reply.
Flag¶
This endpoint allows you to flag an existing user review, 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 review.
- POST /api/v3/reviews/review/(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
review_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
review_flag_reason_spam
Spam or otherwise non-review content
review_flag_reason_language
Inappropriate language/dialog
review_flag_reason_bug_support
Misplaced bug report or support request
review_flag_reason_other
Other (please specify)