=======
Ratings
=======

.. note::
    These v4 APIs are now frozen.
    See :ref:`the API versions available<api-versions-list>` for details of the
    different API versions available.
    The only authentication method available at
    the moment is :ref:`the internal one<v4-api-auth-internal>`.

------------
List ratings
------------

.. rating-list:

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.

.. http:get:: /api/v4/ratings/rating/

    :query string addon: The :ref:`add-on <v4-addon-detail>` 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.
    :query string exclude_ratings: Exclude ratings by their ``id``. Multiple ratings can be specified, separated by comma(s).
    :query string filter: The :ref:`filter(s) <v4-rating-filtering-param>` to apply.
    :query string score: Only include ratings that have been given a specific ``score``. Multiple scores can be specified, separated by comma(s).
    :query string show_flags_for: 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 :ref:`ratings <v4-rating-detail-object>`.
    :query boolean show_grouped_ratings: 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).
    :query string show_permissions_for: 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.
    :query int user: The user id to fetch ratings from.
    :query int version: The version id to fetch ratings from.
    :query int page: 1-based page number. Defaults to 1.
    :query int page_size: Maximum number of results to return for the requested page. Defaults to 25.
    :>json int count: The number of results for this query.
    :>json string next: The URL of the next page of results.
    :>json string previous: The URL of the previous page of results.
    :>json array results: An array of :ref:`ratings <v4-rating-detail-object>`.
    :>json boolean can_reply: 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.
    :>json object grouped_ratings: 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}``.

.. _v4-rating-filtering-param:

   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
------

.. rating-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.


.. http:get:: /api/v4/ratings/rating/(int:id)/

    .. _v4-rating-detail-object:

    :query string show_flags_for: 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.
    :>json int id: The rating id.
    :>json object addon: A simplified :ref:`add-on <v4-addon-detail-object>` object that contains only a few properties: ``id``, ``name``, ``icon_url`` and ``slug``.
    :>json string|null body: The text of the rating.
    :>json boolean is_deleted: Boolean indicating whether the rating has been deleted or not.
    :>json boolean is_latest: Boolean indicating whether the rating is the latest posted by the user on the same add-on.
    :>json int previous_count: The number of ratings posted by the user on the same add-on before this one.
    :>json object flags[]: 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.
    :>json string flags.flag: A :ref:`constant<v4-rating-flag-constants>` describing the reason behind the flagging.
    :>json string|null flags.note: A note to explain further the reason behind the flagging if ``flag`` was ``rating_flag_reason_other``; null otherwise.
    :>json int score: The score the user gave as part of the rating.
    :>json object|null reply: The rating object containing the developer reply to this rating, if any (The fields ``rating``, ``reply`` and ``version`` are omitted).
    :>json int version.id: The add-on version id the rating applies to.
    :>json string version.version: The add-on version string the rating applies to.
    :>json object user: Object holding information about the user who posted the rating.
    :>json string user.id: The user id.
    :>json string user.name: The user name.
    :>json string user.url: The user profile URL.
    :>json string user.username: The user username.

----
Post
----

.. rating-post:

This endpoint allows you to post a new rating for a given add-on and version.
If successful a :ref:`rating object <v4-rating-detail-object>` is returned.

 .. note::
     Requires authentication.


.. http:post:: /api/v4/ratings/rating/

    :<json string addon: The add-on id the rating applies to (required).
    :<json string|null body: The text of the rating.
    :<json int score: The score the user wants to give as part of the rating (required).
    :<json int version: The add-on version id the rating applies to (required).

----
Edit
----

.. rating-edit:

This endpoint allows you to edit an existing rating by its id.
If successful a :ref:`rating object <v4-rating-detail-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.

.. http:patch:: /api/v4/ratings/rating/(int:id)/

    :<json string|null body: The text of the rating.
    :<json int score: The score the user wants to give as part of the rating.


------
Delete
------

.. 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.

.. http:delete:: /api/v4/ratings/rating/(int:id)/


-----
Reply
-----

.. rating-reply:

This endpoint allows you to reply to an existing user rating.
If successful a :ref:`rating reply object <v4-rating-detail-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.

.. http:post:: /api/v4/ratings/rating/(int:id)/reply/

    :<json string body: The text of the reply (required).


----
Flag
----

.. rating-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.

.. http:post:: /api/v4/ratings/rating/(int:id)/flag/

    :<json string flag: A :ref:`constant<v4-rating-flag-constants>` describing the reason behind the flagging.
    :<json string|null note: 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.
    :>json object: If successful, an object with a ``msg`` property containing a success message. If not, an object indicating which fields contain errors.

.. _v4-rating-flag-constants:

    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)
    ===============================  ==========================================