Barrister lets you write well documented services that can be consumed from a variety of languages.
The basic steps are:
- Write an IDL file (See: http://barrister.bitmechanic.com/docs.html)
- Run the
barrister
tool to convert the IDL file to JSON and HTML files (or use the hosted translator -- see below) - Install the language binding for the lanuage you're writing the server in (See: http://barrister.bitmechanic.com/download.html)
- Write a server that implements the interfaces in the IDL
This project contains the core barrister
command line tool as well as the Python bindings.
If you are working in a language other than Python and don't wish to install the barrister Python package, you can use the hosted translator to convert your IDL to its JSON representation. For example:
curl --data-urlencode idl@foo.idl http://barrister.bitmechanic.com/run > foo.json
This would upload foo.idl
and save the output as foo.json
. Currently the hosted error output is fairly
minimal, but if you get valid JSON back on the response then you should be set.
I suggest installing pip. All Python distributions that I'm aware of ship with easy_install
, so if
you don't have pip
yet, you can try:
easy_install pip
Then you simply run:
pip install --pre barrister
You may need to be root to install packages globally, in which case you should su
to root or
use sudo
:
sudo pip install --pre barrister
Note - the --pre
tag is currently required to get install the Plex dependency.
If you're using Python 2.6 or later, you're good to go. Python 2.5 users will need to:
pip install simplejson
Python 2.3 and 2.4 users will need to:
pip install uuid simplejson
As of 0.1.3 barrister can optionally generate UML-ish diagrams using Graphviz.
To generate a diagram, use the -p
and optionally -z
flags to barrister.
The Graphviz dot
program must be installed and in your PATH. See the
Graphviz site for installation details. Most Linux distros can install
Graphviz via a package manager (apt, yum, pacman, etc). Mac users can install
Graphviz with homebrew.
If you'd like the diagram embedded in the generated HTML doc, place the token:
[[diagram]]
in your IDL file where you'd like the diagram to appear. This
string will be replaced with a HTML <img>
tag pointing to the diagram.
- Read the Contact Service Tutorial
- Read the IDL Docs for more info on writing Barrister IDL files
- View the API Reference based on the latest commit to master
Distributed under the MIT license. See LICENSE file for details.
Note to self on how to tag release
# Edit `setup.py` and `__init__.py`, bump version, then run:
git add -u
git commit -m "bump v0.1.0"
git tag -a v0.1.0 -m "version 0.1.0"
git push --tags
git push
python setup.py sdist upload