.Gather

Integrating the GatherContent API with .Net

Abe Taylor

Sitecore Practice Lead

Date

08.26.2016

Introduction

Content Management Systems are great. I mean, eventually they are. Day one, though...

Your templates aren't built.
Your content structure probably isn't defined.
Authors were ready to start creating their content before you even got through requirements.

Getting to a point where you can define and rapidly change content types, structure, and templates is plagued with "what do these buttons do," "where's my image," "we need workflows!"

GatherContent allows us to quickly start new projects, define content templates, set up content review and approvals. We repeatedly find that it's a great tool for curating and developing content before authors are able to access their CMS. It keeps content authors focused on content. Not headers, footers, navigation, and, and, and.

..."what do these buttons do," "where's my image," "we need workflows!"

The Problem

But what happens during this process when content needs translating? Have we created all the new content we need and kept the stuff we want? Can we compare this to our content inventory? Please don't tell me that we're cut-copy-and-pasting our way through all of this...

Good news for everyone: GatherContent does have an API–a pretty extensive one, but writing a new script or program for each scenario quickly gets out of hand. While there is an API, there wasn't a .Net implementation, which meant that our custom applications were not only one-offs–they didn't follow any real pattern or create anything that we could reuse.

We fixed that.

Please don't tell me that we're cut-copy-and-pasting our way through all of this...

The Solution

We set out to develop a .Net library that wrapped all the features of the GatherContent API and would be a single point of access for any integration point in the future.

We call it .Gather (dot-Gather) and it allows developers to do anything the GatherContent API currently allows.

We couldn't help ourselves, though. We made a few changes – not to the API, but to how we wanted to use it.

JSON Contract Resolver

The default API uses lower, underscore casing for property names in JSON output. This didn't match our preference for Pascal casing for properties and classes. A custom DefaultContractResolver class that overrides the default JSON.Net ResolvePropertyName got a little RegEx treatment. Class and property mapping now takes place without decorating every property with attributes.

Avatars

It's nice to see who touched a piece of content. If they've uploaded an avatar, they want you to see it too. The API returns the image name, but stops there. Without a little more path, you won't get to enjoy Tara's cat picture. Since this is critical information, we add the full path. Enjoy.

Step Reduction

If you're creating new GatherContent items or updating them, you've got a few steps the API expects. Let's assume you've already got the right JSON string for the section. You'll need to base64 encode it. Now URL encode the encoded string.

Maybe you're getting an item to update? Get it. URL decode it. Decode it again. Deserialize it. Extract the section you need. Make changes. Reverse the process.

.Gather libraries do this all for you when the API expects it.

GatherContent Data Wrapper

Many of the API calls wrap the response details in a Data object. To simplify notation and readability, we customized the deserialization process to remove the wrapper when present. Don't worry–we keep it around. You can just ask for CurrentUser.Email and not CurrentUser.Data.Email.

Project Structure Representation

In GatherContent, the data is in a hierarchy. In a target system, the data is in a hierarchy. In the API, the data is flat. Yes, there's a parent-child relationship using identifiers. Assuming that you'd like to keep this structure in code, we've added an OrganizeItems method that maps out this hierarchy for you. Or, use it flat.

Where to find it?

Getting the latest stable release

.Gather is distributed as a NuGet package with the dependencies and configuration needed, installed the way you're used to:

PM> Install-Package DotGather

Configuring .Gather

There are 3 configuration settings specific to the application.

ApiUrl - This configuration setting will come pre-filled out to point to GatherContent's web API by default. No change is necessary here.
ApiUser - The ApiUser setting will need to be updated with the GatherContent username for the identity you want your application to execute.
ApiKey - The ApiKey is the generated key given to a user by GatherContent for them to access the API. When you have this key, paste it into the ApiKey setting in the App.config file. More information can be found on how to get your API key here.

Example:

<appSettings>
    <add key="ApiUrl" value="https://api.gathercontent.com/" />
    <add key="ApiUser" value="myName@Test.com" />
    <add key="ApiKey" value="9ymn2v2-0h94-3ll5-icxm-i5281j896w90" />
</appSettings>

Documentation

In order to provide the most insight into the .Gather library, what methods and classes there are, we have provided MSDN flavored documentation that developers can explore here.

The Source Code

.Gather is an open source solution, hosted on GitHub and available for any developer/organization to branch and use for their own projects. You can find the source code here on GitHub.