diff options
Diffstat (limited to 'docs/en/rst/api/core/v1/attachment.rst')
| -rw-r--r-- | docs/en/rst/api/core/v1/attachment.rst | 357 |
1 files changed, 357 insertions, 0 deletions
diff --git a/docs/en/rst/api/core/v1/attachment.rst b/docs/en/rst/api/core/v1/attachment.rst new file mode 100644 index 000000000..22a57af60 --- /dev/null +++ b/docs/en/rst/api/core/v1/attachment.rst @@ -0,0 +1,357 @@ +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", + "is_markdown" : true, + "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. +is_markdown boolean If set to ``true``, the comment has Markdown structures; + otherwise, it is normal text. +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", + "is_markdown" : true, + "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. +is_markdown boolean If set to ``true``, the comment has Markdown structures; + otherwise, it is normal text. +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. +================ ======== ===================================================== |