attachment.rst

Attachments
===========

The Bugzilla API for creating, changing, and getting the details of attachments.

.. _rest_attachments:

Get Attachment
--------------

This allows you to get data about attachments, given a list of bugs and/or
attachment IDs. Private attachments will only be returned if you are in the
appropriate group or if you are the submitter of the attachment.

**Request**

To get all current attachments for a bug:

.. code-block:: text

   GET /rest/bug/(bug_id)/attachment

To get a specific attachment based on attachment ID:

.. code-block:: text

   GET /rest/bug/attachment/(attachment_id)

One of the below must be specified.

=================  ====  ======================================================
name               type  description
=================  ====  ======================================================
**bug_id**         int   Integer bug ID.
**attachment_id**  int   Integer attachment ID.
=================  ====  ======================================================

**Response**

.. code-block:: js

   {
      "bugs" : {
         "1345" : [
            { (attachment) },
            { (attachment) }
         ],
         "9874" : [
            { (attachment) },
            { (attachment) }
         ],
      },
      "attachments" : {
         "234" : { (attachment) },
         "123" : { (attachment) },
      }
   }

An object containing two elements: ``bugs`` and ``attachments``.

The attachments for the bug that you specified in the ``bug_id`` argument in
input are returned in ``bugs`` on output. ``bugs`` is a object that has integer
bug IDs for keys and the values are arrays of objects as attachments.
(Fields for attachments are described below.)

For the attachment that you specified directly in ``attachment_id``, they
are returned in ``attachments`` on output. This is a object where the attachment
ids point directly to objects describing the individual attachment.

The fields for each attachment (where it says ``(attachment)`` in the
sample response above) are:

================  ========  =====================================================
name              type      description
================  ========  =====================================================
data              base64    The raw data of the attachment, encoded as Base64.
size              int       The length (in bytes) of the attachment.
creation_time     datetime  The time the attachment was created.
last_change_time  datetime  The last time the attachment was modified.
id                int       The numeric ID of the attachment.
bug_id            int       The numeric ID of the bug that the attachment is
                            attached to.
file_name         string    The file name of the attachment.
summary           string    A short string describing the attachment.
content_type      string    The MIME type of the attachment.
is_private        boolean   ``true`` if the attachment is private (only visible
                            to a certain group called the "insidergroup",
                            ``false`` otherwise.
is_obsolete       boolean   ``true`` if the attachment is obsolete, ``false``
                            otherwise.
is_patch          boolean   ``true`` if the attachment is a patch, ``false``
                            otherwise.
creator           string    The login name of the user that created the
                            attachment.
flags             array     Array of objects, each containing the information
                            about the flag currently set for each attachment.
                            Each flag object contains items descibed in the
                            Flag object below.
================  ========  =====================================================

Flag object:

=================  ========  ====================================================
name               type      description
=================  ========  ====================================================
id                 int       The ID of the flag.
name               string    The name of the flag.
type_id            int       The type ID of the flag.
creation_date      datetime  The timestamp when this flag was originally created.
modification_date  datetime  The timestamp when the flag was last modified.
status             string    The current status of the flag such as ?, +, or -.
setter             string    The login name of the user who created or last
                             modified the flag.
requestee          string    The login name of the user this flag has been
                             requested to be granted or denied. Note, this field
                             is only returned if a requestee is set.
=================  ========  ====================================================

.. _rest_add_attachment:

Create Attachment
-----------------

This allows you to add an attachment to a bug in Bugzilla.

**Request**

To create attachment on a current bug:

.. code-block:: text

   POST /rest/bug/(bug_id)/attachment

.. code-block:: js

   {
     "ids" : [ 35 ],
     "is_patch" : true,
     "comment" : "This is a new attachment comment",
     "summary" : "Test Attachment",
     "content_type" : "text/plain",
     "data" : "(Some patch content)",
     "file_name" : "test_attachment.patch",
     "obsoletes" : [],
     "is_private" : false,
     "flags" : [
       {
         "name" : "review",
         "status" : "?",
         "requestee" : "user@bugzilla.org",
         "new" : true
       }
     ]
   }


The params to include in the POST body, as well as the returned
data format, are the same as below. The ``bug_id`` param will be
overridden as it it pulled from the URL path.

================  =======  ======================================================
name              type     description
================  =======  ======================================================
**ids**           array    The IDs or aliases of bugs that you want to add this
                           attachment to. The same attachment and comment will be
                           added to all these bugs.
**data**          string   The content of the attachment. If the content of the
                           attachment is not ASCII text such as
                           ``application/octet-stream`` you must encode it in
                           base64 using an appropriate client library such as
                           ``MIME::Base64`` for Perl.
**file_name**     string   The "file name" that will be displayed in the UI for
                           this attachment and also downloaded copies will be
                           given.
**summary**       string   A short string describing the attachment.
**content_type**  string   The MIME type of the attachment, like ``text/plain``
                           or ``image/png``.
comment           string   A comment to add along with this attachment.
is_patch          boolean  ``true`` if Bugzilla should treat this attachment as a
                           patch. If you specify this, you do not need to specify
                           a ``content_type``. The ``content_type`` of the
                           attachment will be forced to ``text/plain``. Defaults
                           to ``false`` if not specified.
is_private        boolean  ``true`` if the attachment should be private
                           (restricted to the "insidergroup"), ``false`` if the
                           attachment should be public. Defaults to ``false`` if
                           not specified.
flags             array    Flags objects to add to the attachment. The object
                           format is described in the Flag object below.
================  =======  ======================================================

Flag object:

To create a flag, at least the ``status`` and the ``type_id`` or ``name`` must
be provided. An optional requestee can be passed if the flag type is requestable
to a specific user.

=========  ======  ==============================================================
name       type    description
=========  ======  ==============================================================
name       string  The name of the flag type.
type_id    int     The internal flag type ID.
status     string  The flags new status (i.e. "?", "+", "-" or "X" to clear a
                   flag).
requestee  string  The login of the requestee if the flag type is requestable to
                   a specific user.
=========  ======  ==============================================================

**Response**

.. code-block:: js

   {
     "ids" : [
       "2797"
     ]
   }

====  =====  =========================
name  type   description
====  =====  =========================
ids   array  Attachment IDs created.
====  =====  =========================

.. _rest_update_attachment:

Update Attachment
-----------------

This allows you to update attachment metadata in Bugzilla.

**Request**

To update attachment metadata on a current attachment:

.. code-block:: text

   PUT /rest/bug/attachment/(attachment_id)

.. code-block:: js

   {
     "ids" : [ 2796 ],
     "summary" : "Test XML file",
     "comment" : "Changed this from a patch to a XML file",
     "content_type" : "text/xml",
     "is_patch" : 0
   }

=================  =====  =======================================================
name               type   description
=================  =====  =======================================================
**attachment_id**  int    Integer attachment ID.
**ids**            array  The IDs of the attachments you want to update.
=================  =====  =======================================================

============  =======  ==========================================================
name          type     description
============  =======  ==========================================================
file_name     string   The "file name" that will be displayed in the UI for this
                       attachment.
summary       string   A short string describing the attachment.
comment       string   An optional comment to add to the attachment's bug.
content_type  string   The MIME type of the attachment, like ``text/plain``
                       or ``image/png``.
is_patch      boolean  ``true`` if Bugzilla should treat this attachment as a
                       patch. If you specify this, you do not need to specify a
                       ``content_type``. The ``content_type`` of the attachment
                       will be forced to ``text/plain``.
is_private    boolean  ``true`` if the attachment should be private (restricted
                       to the "insidergroup"), ``false`` if the attachment
                       should be public.
is_obsolete   boolean  ``true`` if the attachment is obsolete, ``false``
                       otherwise.
flags         array    An array of Flag objects with changes to the flags. The
                       object format is described in the Flag object below.
============  =======  ==========================================================

Flag object:

The following values can be specified. At least the ``status`` and one of
``type_id``, ``id``, or ``name`` must be specified. If a type_id or name matches
a single currently set flag, the flag will be updated unless ``new`` is specified.

=========  =======  =============================================================
name       type     description
=========  =======  =============================================================
name       string   The name of the flag that will be created or updated.
type_id    int      The internal flag type ID that will be created or updated.
                    You will need to specify the ``type_id`` if more than one
                    flag type of the same name exists.
status     string   The flags new status (i.e. "?", "+", "-" or "X" to clear a
                    flag).
requestee  string   The login of the requestee if the flag type is requestable
                    to a specific user.
id         int      Use ID to specify the flag to be updated. You will need to
                    specify the ``id`` if more than one flag is set of the same
                    name.
new        boolean  Set to true if you specifically want a new flag to be
                    created.
=========  =======  =============================================================

**Response**

.. code-block:: js

   {
     "attachments" : [
       {
         "changes" : {
           "content_type" : {
             "added" : "text/xml",
             "removed" : "text/plain"
           },
           "is_patch" : {
             "added" : "0",
             "removed" : "1"
           },
           "summary" : {
             "added" : "Test XML file",
             "removed" : "test patch"
           }
         },
         "id" : 2796,
         "last_change_time" : "2014-09-29T14:41:53Z"
       }
     ]
   }

``attachments`` (array) Change objects with the following items:

================  ========  =====================================================
name              type      description
================  ========  =====================================================
id                int       The ID of the attachment that was updated.
last_change_time  datetime  The exact time that this update was done at, for this
                            attachment. If no update was done (that is, no fields
                            had their values changed and no comment was added)
                            then this will instead be the last time the
                            attachment was updated.
changes           object    The changes that were actually done on this
                            attachment. The keys are the names of the fields that
                            were changed, and the values are an object with two
                            items:

                            * added: (string) The values that were added to this
                              field. Possibly a comma-and-space-separated list
                              if multiple values were added.
                            * removed: (string) The values that were removed from
                              this field.
================  ========  =====================================================