Over a million developers have joined DZone.

Collaborator's New API Feature - Part 1

· Integration Zone

Is iPaaS solving the right problems? Not knowing the fundamental difference between iPaaS and dPaaS could cost you down the road. Brought to you in partnership with Liaison Technologies.

 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.

Discover the unprecedented possibilities and challenges, created by today’s fast paced data climate and why your current integration solution is not enough, brought to you in partnership with Liaison Technologies.

Topics:

Published at DZone with permission of Denis Goodwin, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

SEE AN EXAMPLE
Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
Subscribe

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

{{ parent.tldr }}

{{ parent.urlSource.name }}