Attach a Related File to an Issue

A new attachment can be added to an existing issue simply by sending an HTTP POST request containing the file to be attached.

Python 2 example of adding an attachment to an existing issue

Unlike the other examples, httplib2 is not used in this example as it does have the ability to stream a file upload. The example uses the standard urllib2 module and poster module instead. The poster module removes the need to load the entire file into memory before submitting the request.

The poster module can be downloaded from the poster module website. The poster module is provided as a .egg Python archive which can be easily installed using the EasyInstall module, which is packaged with the setuptools package. Follow the installations instructions for your platform to install setuptools, then follow the instructions to install the poster .egg archive.


# Araxis Ketura API Script Example.
# Copyright (c) 2009 Araxis Ltd. All rights reserved.
# Redistribution and use of this example code, with or without modification, are hereby permitted.

# import required classes from modules
from poster.encode import multipart_encode
from poster.streaminghttp import register_openers
import urllib2
import base64

# register the streaming http handlers with urllib2

# start the multipart/form-data encoding of the file ""
# headers contains the necessary Content-Type and Content-Length
# datagen is a generator object that yields the encoded parameters
# poster encodes parts in UTF-8 by default
datagen, headers = multipart_encode({"File": open(""), "Description": "Python script to demonstrate file attachment"})

# create the Request object
request = urllib2.Request("http://localhost:9453/Ketura/API/Issues/1001/Attachments", datagen, headers)

# set user credentials
username = 'es'
password = 'pw'
base64string = base64.encodestring('%s:%s' % (username, password))[:-1]
authheader = "Basic %s" % base64string
request.add_header("Authorization", authheader)

# actually do the request, and get the response
print urllib2.urlopen(request).read()

[Download This Example | Download Complete Example]

This example differs from the other examples that use the POST method. The file is sent as part of a multipart HTML form, rather than the a usual HTML form. A multipart form is used so that the file can be encoded in one part of the request, while the description of the file is encoded in another. Ketura is able to understand the multipart form and create the file as an attachment related to the issue.


A summary of the web service to create an issue attachment:

Resource path /Issues/{id}/Attachments
Accepted HTTP methods OPTIONS*, POST

* Sending an OPTIONS request will generate a response containing a WADL document. This document describes the services available from this resource path.

POST summary

HTTP method POST
Request media type multipart/form-data
Request format HTML multipart form
Successful response code 204
Authentication method Basic HTTP Authentication

POST data

Name Description Required Can Be Empty Maximum Length
Description A short description of the contents of the file to be attached. yes yes 255 characters
File The file to be attached to the issue. yes yes 10 MB

POST response

Response Code(s) Significant Response Headers Response Response MIME Type
204 None None n/a
401, 500 and greater None Text containing java stack trace text/plain
Others None HTML error page text/html