.. _set-review-request-draft-field:

==============================
Set Review Request Draft Field
==============================

:Path: ``api/json/reviewrequests/{review_request_id}/draft/set/{field_name}/``


URL Parameters
==============

+-------------------+---------+-------------------------------------+
| Parameter         | Type    | Description                         |
+===================+=========+=====================================+
| review_request_id | Integer | The ID of the review request.       |
+-------------------+---------+-------------------------------------+
| field_name        | String  | The name of the field to set.       |
+-------------------+---------+-------------------------------------+


HTTP POST
=========

Sets the value of a field in the review request's draft.

If a draft doesn't yet exist, this will create one.

The following fields can be modified through this call:

+-------------------+---------+-------------------------------------------+
| Field             | Type    | Description                               |
+===================+=========+===========================================+
| branch            | String  | The branch the code applies to.           |
+-------------------+---------+-------------------------------------------+
| bugs_closed       | String  | Comma-separated list of bug numbers/IDs.  |
+-------------------+---------+-------------------------------------------+
| changedescription | String  | The custom description of the changes in  |
|                   |         | this draft.                               |
+-------------------+---------+-------------------------------------------+
| description       | String  | The review request's description.         |
+-------------------+---------+-------------------------------------------+
| summary           | String  | The review request's summary.             |
+-------------------+---------+-------------------------------------------+
| target_groups     | String  | Comma-separated list of target review     |
|                   |         | groups.                                   |
+-------------------+---------+-------------------------------------------+
| target_people     | String  | Comma-separated list of target reviewers. |
+-------------------+---------+-------------------------------------------+
| testing_done      | String  | The testing done on the review request.   |
+-------------------+---------+-------------------------------------------+

It also allows for setting screenshot captions through a special field
name. Any ``field_name`` matching ``screenshot_{id}_caption`` will set the
caption of the screenshot with that ID.


Example Request
---------------

.. code-block:: none

    POST /api/json/reviewrequests/12321/draft/set/summary/


Responses
---------

HTTP 200: Success
~~~~~~~~~~~~~~~~~

On success, the resulting payload will contain an entry for the field
name being modified, along with its value. If there was any validation
issue with the field name, an entry with the field name prepended with
``invalid_`` will be added, with the error.


Example Response
^^^^^^^^^^^^^^^^

.. code-block:: javascript

    {
      stat: "ok",
      summary: "This is the new summary"
    }


HTTP 400: Bad Request
~~~~~~~~~~~~~~~~~~~~~

Error 102: Invalid Attribute
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The field you attempted to set doesn't exist.

+-----------+---------+------------------------------------+
| Field     | Type    | Description                        |
+===========+=========+====================================+
| attribute | String  | The field name that was being set. |
+-----------+---------+------------------------------------+


Error 105: Invalid Form Data
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The value specified for the field is invalid.

You may get this if you specify a summary value that has a newline in it.

+-----------+---------+------------------------------------+
| Field     | Type    | Description                        |
+===========+=========+====================================+
| attribute | String  | The field name that was being set. |
+-----------+---------+------------------------------------+
| detail    | String  | The validation error information.  |
+-----------+---------+------------------------------------+


HTTP 401: Unauthorized
~~~~~~~~~~~~~~~~~~~~~~

Error 103: Not Logged In
^^^^^^^^^^^^^^^^^^^^^^^^

The client making the request is not logged in.

See :ref:`authenticating` for more information.


HTTP 403: Forbidden
~~~~~~~~~~~~~~~~~~~

Error 101: Permission Denied
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The user the client is logged in as doesn't have permission to modify the
draft.


HTTP 404: Not Found
~~~~~~~~~~~~~~~~~~~

Error 100: Does Not Exist
^^^^^^^^^^^^^^^^^^^^^^^^^

The review request doesn't have an associated draft.


No Error Payload
^^^^^^^^^^^^^^^^

The review request with the given ``review_request_id`` does not exist on the
server.


.. comment: vim: ft=rst et ts=3
