Zdesk is a Python wrapper for the Zendesk API. This library provides an easy and flexible way for developers to communicate with their Zendesk account in their application.
See the Zendesk developer site for API
documentation. The underlying zdesk_api
module has been automatically
generated
from this documentation.
Zdesk works with both Python 2 and Python 3. Tested on Python 2.7.5 and 3.4.1.
httplib2 is used for authentication and requests
(pip install | easy_install) httplib2
simplejson is used to serialize and deserialize requests and responses
(pip install | easy_install) simplejson
Zdesk is available on pypi, so installation should be fairly simple:
(pip install | easy_install) zdesk
- zdeskcfg: Automatically configure your zdesk scripts from a configuration file and command line arguments.
- zdgrab: Download and decompress ticket attachments.
Zdesk attempts to identify query string parameters from the online
documentation. All query string parameters are optional (default to None
),
and are provided for convenience and reference.
However, it is very difficult, if not impossible, to accurately capture all valid query parameters for a particular endpoint from the documentation. So, zdesk passes all provided kwargs on to the Zendesk API as query string parameters without validation, except those that it has reserved for its own use. The current reserved kwargs (described in more detail below) are:
complete_response
get_all_pages
mime_type
There are a few common query string parameters that the Zendesk API accepts for many calls. The current list at the time of this writing is:
include
page
per_page
sort_by
sort_order
Under normal circumstances, when a call is made and the response indicates success, the value returned will be formatted to simplify usage. So if a JSON response is returned with the expected return code, then instead of getting back all of the HTTP response information, headers and all, the only thing that is returned is the JSON, which will already be deserialized. In some cases, only a single string in a particular header (location) is returned, and so that will be the return value.
Passing complete_response=True
will cause all response information to be
returned, which is the result of an httplib2.client.request
.
There is a common pattern where a request will return one page of data along
with a next_page
location. In order to retrieve all results, it is necessary
to continue retrieving every next_page
location. The results then all need to
be processed together. A loop to get all pages ends up stamped throughout
Zendesk code, since many API methods return paged lists of objects.
As a convenience, passing get_all_pages
to any API method will do this for
you, and will also merge all responses. The result is a single, large object
that appears to be the result of one single call. The logic for this
combination and reduction is well documented in the
source
(look for the line reading Now we need to try to combine or reduce the results
, if the line number has shifted since this writing).
By default, all data
passed to requests is assumed to be of MIME type
application/json
. The value of data
in this default case should be a JSON
object, and it will automatically be converted using json.dumps
for the
request.
Some endpoints such as those that allow file uploads expect data
to be of a
different MIME type, and so this can be specified using the mime_type
keyword
argument.
If working with files of an unknown MIME type, a module such as python-magic can be useful. The following code has worked well with zdesk scripts:
# import, configure, and connect to Zendesk as shown in the example code.
# zd = Zendesk(...
import magic
fname = 'my_file'
mime_type = magic.from_file(fname, mime=True)
if type(mime_type) is bytes:
mime_type = mime_type.decode()
with open(fname, 'rb') as fp:
fdata = fp.read()
response = zd.upload_attachment(filename=fname,
data=fdata, mime_type=mime_type, complete_response=True)
upload_token = response['content']['upload']['token']
from zdesk import Zendesk
################################################################
## NEW CONNECTION CLIENT
################################################################
# Manually creating a new connection object
zendesk = Zendesk('https://yourcompany.zendesk.com', '[email protected]', 'passwd')
# If using an API token, you can create connection object using
# zendesk = Zendesk('https://yourcompany.zendesk.com', '[email protected]', 'token', True)
# True specifies that the token is being used instead of the password
# See the zdeskcfg module for more sophisticated configuration at
# the command line and via a configuration file.
# https://github.com/fprimex/zdeskcfg
# Are you getting an error such as...
# "SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed"?
#zendesk = Zendesk('https://yourcompany.zendesk.com', '[email protected]', 'passwd',
# client_args={
# "disable_ssl_certificate_validation": True
# }
#)
################################################################
## TICKETS
################################################################
# List
zendesk.tickets_list()
# Create
new_ticket = {
'ticket': {
'requester_name': 'Howard Schultz',
'requester_email': '[email protected]',
'subject':'My Starbucks coffee is cold!',
'description': 'please reheat my coffee',
'set_tags': 'coffee drinks',
'ticket_field_entries': [
{
'ticket_field_id': 1,
'value': 'venti'
},
{
'ticket_field_id': 2,
'value': '$10'
}
]
}
}
# Create the ticket and get its URL
result = zendesk.ticket_create(data=new_ticket)
# Need ticket ID?
from zdesk import get_id_from_url
ticket_id = get_id_from_url(result)
# Show
zendesk.ticket_show(id=ticket_id)
# Delete
zendesk.ticket_delete(id=ticket_id)
See the full example file on github, however this is not anywhere close to covering all of the over 400 REST API methods.