Over a million developers have joined DZone.

Collaborator's New API Feature - Part 1

DZone's Guide to

Collaborator's New API Feature - Part 1

· Integration Zone ·
Free Resource

How to Transform Your Business in the Digital Age: Learn how organizations are re-architecting their integration strategy with data-driven app integration for true digital transformation.

 This is part one of the technical series about Collaborator’s new API feature.

Collaborator has a brand new API, and I wanted to see what I could do with it. But what would be useful? What benefit would this have, other than being a learning experience for me?

A couple of guys around the office had mentioned possibly creating an Add-In for Microsoft Word. I overheard, and soon after I was off to the races. I knew enough about Microsoft Word’s architecture to be dangerous, as I had written several Office plugins in a former life. This was going to be easy! Or was it?

Before creating a Word plugin, I needed to know what was involved; more specifically I needed to know how to send requests to Collaborator’s new API. Beyond just sending a request, I needed to understand the authentication mechanism and I needed to know how to send the appropriate commands to create a review with a document attached. That also required that I get the document from my local copy of Word to Collaborator, which meant uploading it.

But how would I send a file to this new web service?

Here’s the story of my journey, and the creation of a simple Office plugin, revolving around the Collaborator JSON/RPC API.

The story begins with JSON. What is it? It’s an acronym for JavaScript Object Notation. How is it implemented? Well, that’s not so straight forward.

After reading the API documentation, I learned that Collaborator accepts HTTP POST requests at /services/json/v1. The request needs to be a list of commands paired with the arguments for each.

     {"command" : "ServerInfoService.getVersion"
     {"command" : "Examples.echo",
     "args" : {"echo" : "Some text."}

The server will then return a list of response objects which correlate to the requests. Each response object is either an error message, or the result data from the request command.

     { "result" : { "version" : "9.1.9100" } },
     { "result" : { "echo" : "Some text." } },

In theory, it sounds simple enough, but implementing it required a bit of thought. What’s the easiest way to generate the JSON request string? What is the easiest way to process the JSON response from the server?

I could just build the strings by hand, substituting in appropriate values for the variables, but that wasn’t robust enough. It wasn’t simple enough to maintain, and it was going to be error prone. I needed something better.

The answer was quite simple: JSON serialization. Almost all modern languages provide this mechanism in one way or another, either natively, or with the help of open source or commercially available libraries. JavaScript supports it natively, but you can’t write a Word plugin in JavaScript, it needs to be C#. Microsoft provides the System.Runtime.Serialization.Json namespace as a part of the .NET framework which can do just that. However, it’s a bit complicated to use, so I chose to use the Json.NET third party library from Newtonsoft.

With Json.NET, I could take a vanilla C# class, instantiate it, and then turn it into a JSON string with ease.

public class JsonRequest
                string command;
                List args;

JsonRequest myRequest = new JsonRequest();
myRequest.command = "ServerInfoService.getVersion";

string json = JsonConvert.SerializeObject(myRequest);

The resulting JSON string was exactly what I needed:

 "command" : "ServerInfoService.getVersion"

Inverting this process was equally simple, if I had this string variable full of JSON:

string json = "{'command' : 'ServerInfoService.getVersion'}";

Then, I could turn it into a JSONRequest object like this:

JsonRequest myRequest = JsonConvert.DeserializeObject<JsonRequest>;

Simple! I would then find that the MyRequest object had its command value set to “ServerInfoService.getVersion.”

This would become one of the foundational building blocks of the plug in. The ability to predefine my data contract in the form of .NET classes provided the flexibility, and the simplicity that I needed. It’s a simple and elegant solution that is easy to extend.

In the next installment we’ll be diving deeper into how you put the serialized JsonRequests into action. You can see this in action on GitHub.

Build and deploy API integrations 7x faster. Try the Cloud Elements 100% RESTful platform for 30 days free. Access your trial here.


Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}