Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Zendesk API bindings generator

This package provides zdgen, an API bindings generator for the Zendesk REST API. The code currently generates the file for the zdesk project, but there are more projects planned.


The API generator needs Python 3, requests, BeautifulSoup4, and inflection installed. See the requirements.txt file. There also needs to be a POSIX compliant patch executable in your path for applying the patches. Linux and OSX have this, but on Windows it will need to be installed manually with something like Cygwin.


Pull requests and patches to make zdgen compatible with Python 2 will not be accepted. This is a Python 3 codebase. The output of zdgen for Python, however, is aimed to be Python 2 and Python 3 compliant, and patches to fix Python 2 compatibility in the output are welcome.

Setup and execution

# configure a virtualenv or conda env, etc

$ python install


$ python develop

$ cd somewhere/you/want/to/store/docs/and/output

$ zdgen [options] BACKEND


Full options to zdgen are shown below in the help output:

usage: zdgen [-h] [-out OUTFILE] [-docs DOCDIR] BACKEND

  Generate Zendesk language bindings directly from documentation located at Available Backends are:

  zdesk   - Python 2 and 3 for use with zdesk. File:
  listing - Text file listing of all endpoints. File: listing.txt

positional arguments:
  BACKEND       Programming language to generate binding for

optional arguments:
  -h, --help    show this help message and exit
  -out OUTFILE  Output file for the binding (default: from backend)
  -docs DOCDIR  Directory Zendesk docs will be stored in (default: apidocs)

Under the hood

When zdgen is executed for the first time, the following happens:

  • apidocs dir is deleted if it is present
  • apidocs_orig dir is made if it is not present
  • The introduction pages for each API component is downloaded
  • The intro pages are scraped for all other pages which are downloaded
  • Pages are written into the apidocs_orig dir
  • apidocs_orig is copied to apidocs
  • apidocs pages are patched with the diffs in patches dir
  • Patched apidocs pages are scraped for REST API info
  • Duplicates, redundant, and ambiguous endpoints are resolved
  • The actual code is generated
  • The code is formatted into to the template
  • The backend file is written to the current directory or given path

On subsequent runs, the following happens:

  • apidocs dir is deleted if it is present
  • The introduction pages are located in the apidocs_orig dir
  • The intro pages are scraped for all other pages
  • The needed pages are located in the apidocs_orig dir
  • apidocs_orig is copied to apidocs and the rest happens as before

Developing patches to the documentation

If patches are needed, then to create them I do the following:

  • Remove the patched apidocs dir
  • Copy the apidocs_orig dir to apidocs dir
  • If the file needing an edit has an already existing patch, apply the patch first:
$ cd apidocs
$ patch -p1 < path/to/source/or/package/install/patches/core_stuff
  • Edit the file as needed
  • Generate a new patch, potentially replacing the old patch
$ cd ..
$ diff -r -u apidocs_orig apidocs > path/to/source/patches/core_stuff

NOTE: Work on patching only one file at a time. If another patch needs to be made, then the apidocs directory needs to be removed again, then recopied from the apidocs_orig directory. This ensures that the patches are for only one file at a time.

Documenting what has changed since the last generation

After generation I typically review the file to see what has changed and to ensure that there are no new syntax problems and so forth. I diff the old and new file, and also specifically look at the methods.

$ diff -u ../zdesk/

$ grep -E '^ *def' ../zdesk/ > methods_old
$ grep -E '^ *def' > methods_new
$ diff -u methods_old methods_new

Deploying to the zdesk project

Finally, once all is well and I am satisfied with the newly generated

cp path/to/zdesk/source/zdesk/
commit -a

# Document in the commit everything that has changed

Hopefully this will help if someone needs to take this over. It would be great to get patch contributions and feedback on if the generated API needs to be changed somehow to make it nicer.


API binding generator for the Zendesk REST API




No packages published


You can’t perform that action at this time.