We're having a contest! Whoever builds the coolest integration, plugin, or anything that hits the Collaborator API could win a drone. We'll be announcing this today, and I'll update this with a link to the official rules soon.
For those of you interested in competing for a new Parrot AR Drone, or if you are just looking to build something cool around your peer review infrastructure, here's a getting started guide for the Collaborator API.
The first step would likely be the installation of a Collaborator server for you to test against.
the latest version of Collaborator is available here: http://support.smartbear.com/downloads/collaborator/installers-for-collaborator-9
Both the server and client pieces require Oracle Java 1.7+, and should run on any modern operating system. We don’t officially support OSX for the server installation, so I recommend that you avoid attempting that.
Installation is simple:
- Install a Java JRE/JDK 1.7 or 1.8
- Run the server installer, the default options should be fine across the board.
- Setup and configure your Collaborator client if you want to see how we currently integrate with SCMs.
Assuming that you selected the default installation options, the Collaborator server should be listening on port 8080. You’ll need to login to the web portal with the user name admin, and a blank password. You’ll be prompted to fill out the first run screen, and you should automatically get a 30 day, 100-seat trial. If the server was unable to contact our licensing server, then you’ll need to send us (support@smartbear.com) the NodeID from the licensing page, and we will send you a license.
Developers can install the server on their local workstations using the embedded database, and then test locally. The server will not use many system resources with only a single user accessing it. If you near the end of your 30-day trial, you can stop the service, and delete the database.* files from the tomcat subdirectory in the installation folder. That will effectively DELETE ALL DATA IN COLLABORATOR. This may be an efficient way for you to test the server on different workstations without having to contact us for a license.
Alternatively, you can send us the NodeIDs for any instances that you have, and we will generate extended trial licenses for you. A trial server works exactly as a licensed server does, it just stops working when the trial ends, although the admin account will still work. Send the Node ID’s to me, or reply on this e-mail chain, and we’ll get the licenses back to your promptly
Detailed instructions for installing the server: http://codecollaborator.smartbear.com/docs/manual/9.0/quickstart_systemadmin.html
Detailed instructions for installing and configuring the client: http://codecollaborator.smartbear.com/docs/manual/9.0/clients_overview.html
Once you’ve gone through that, the server will be online and ready to review code. Now the fun can begin, and the JSON/RPC service will be located at http://your.collab.server/services/json/v1
If you open that URL in a web browser, then you’ll get an input form with some sample JSON, feel free to click submit and see what happens. From an integration standpoint, requests would be sent to that same URL as an HTTP POST request.
Here’s our API documentation: http://codecollaborator.smartbear.com/docs/manual/9.0/json_api_web_services.html
It has a few examples, and explains how to do some basic things, such as authenticate yourself to the server.
The JSON API Reference section there will show you how to access the API JavaDoc. The JavaDoc describes every available server side method for the particular version of the server that you have installed. If you find something is missing or nor working correctly, then please let me know. The API is new, and the base implementation is designed to perform all functions required by our current client software.
Regarding differences and file versioning: Collaborator supports 8 distinct diff formats, and you should strive to use the Unified diff format if at all possible. The diffs should have as many lines of context as possible, essentially giving you the full content of both the before and after versions of a change list or file. That’s discussed here: http://codecollaborator.smartbear.com/docs/manual/9.0/cmdline_upload_diffs.html
That page also provides a command line example for uploading diff files stored on a local disk. Uploading a diff essentially creates two different version records in the Collaborator database using the diff context to generate both files. When you use the JSON API to create a review, you will likely want to just upload the full content of the two versions of a file, and Collaborator will generate the diff internally when the review is displayed. Instructions for adding content via the API: http://codecollaborator.smartbear.com/docs/manual/9.0/json_upload_review_materials.html
Just in case that wasn’t enough information to give you a running start, here’s some example code in C#: https://github.com/SmartBear/msword-collaborator-addin
Check out the CollabAPI folder there. Some documentation around that example is available here: http://smartbear.com/smartbear-developer-network/microsoft-word-plugin-for-collaborator/
Happy coding,
Rick