cancel
Showing results for 
Search instead for 
Did you mean: 

Getting Started with the Collaborator API

Highlighted
Moderator

Getting Started with the Collaborator API

For those of you 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:

  1. Install a Java JRE/JDK 1.7 or 1.8
  2. Run the server installer, the default options should be fine across the board.
  3. 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. 

 

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 us 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

New Here?
Join us and watch the welcome video:
Building with the Collaborator API

Help Documenation
The Collaborator API is a JSON-RPC API that lets you integrate with Collaborator 9.0 and above. For more information about how the API works, check out the API description here:


Sample Plugins
For an example of an add-in that uses the API, take a look at the Microsoft Word Add-in for Collaborator:


We list all the great plugins our network has already built on this page on the SmartBear website.

Description
SBC2020