A Closer Look at the API Designed To Make Ticket Sharing a Piece of Cake

Moving stuff around is easy, right? I can move files on my computer into different folders just by dragging them around. In my favorite calendar application I can move events to different dates. I can move the events from my work calendar to my home calendar, or even a shared calendar. It’s all pretty easy to do — from a user’s perspective that is.

When I first started thinking about ticket sharing, I remembered a comment by Sam Stephenson of 37signals. In this comment, he talks about moving to-do lists between projects in Basecamp, an online project collaboration tool. On the surface, it seems easy, but there is actually a lot of work going on behind the scenes:

“Moving a milestone needs to move any associated to-do lists and messages. And of course those to-do lists can have to-do items with comments, and attached files, and multiple versions of those files.”

“… we need to make sure that when you follow a URL in an email notification for a moved message, comment or files, you are redirected to its new location.”

He closes with:

“I hope you will see that sometimes even the simplest feature can be much more complicated than it looks from the outside.”

As software developers, we want our users to think that moving things around is easy. We don’t want them to worry about moving related objects or processing jobs in the background. We want moving things to just work. We want moving tickets to just work.

Moving tickets

Before we start digging into the database and moving stuff around, first let’s understand why we want to move tickets. In Zendesk, you can already put a ticket into a different group. You can even assign a different agent to a ticket. So what does moving a ticket mean?

Let's walk through an example real quick.

MondoCam is a camera supplier. MondoCam has partnerships with camera lens manufacturers. Now, a customer writes MondoCam with a question about their lens. MondoCam could open a new ticket with their lens supplier. But, it would be nice if they could just move that ticket into their lens supplier's help desk instead. That way the lens supplier would have a concrete explanation from the customer, and all of the context surrounding the ticket.

That is what we would like to accomplish. Unfortunately, moving tickets back and forth comes with its own set of complications. When MondoCam sends a ticket to their lens supplier, does it disappear from their help desk? What if the customer wants a status update? MondoCam no longer knows the status of the ticket and can not give the customer an update. Once the ticket comes back to MondoCam, is it assigned to a brand new agent?

We can already see that this pattern may be too complicated. So, what if we weren’t moving tickets around, but instead we “shared” tickets with other companies?

Sharing tickets

Maybe we can make this easier on our agents. We could keep track of the tickets for them. We could keep all of the conversations in one place. That way the ticket will always stay assigned to the same agent, and the agent will always know the status of the ticket.

So how would we go about implementing this? We could just keep one copy of the ticket around in our database, and give two accounts access to it. We could copy the ticket over to the other account. There are a number of solutions, but there is one problem that none of them solve.

What if the other help desk is not a Zendesk?

Designing an API

Now we’re not only dealing with our database, we’re dealing with databases controlled by other entities. These databases also have their own schemas. So, how do we transform a Zendesk ticket into a generic ticket? We need a standard transport protocol and a standard set of endpoints.

We can’t force everyone to use specific URLs. We can, however, define a standard and ask other help desks to implement this standard under a base URL of their choosing. Everything underneath that base URL should be dedicated to ticket sharing. Help desks can use whatever base URL they wish. They could, for example, use foo.com/partners or example.com/a/bc/13/syncing_stuff/.

Underneath this base URL, the help desk can implement the ticket sharing API endpoints. Currently the ticket sharing API supports two resource types: agreements and tickets. To prevent spam, a help desk should not blindly accept tickets from anyone. So, before a help desk will accept tickets that help desk must enter into a ticket sharing agreement with another help desk. Once that agreement is in place, the two help desks can communicate with each other.

Currently, the ticket sharing API defines four endpoints under the base URL:

• POST /agreements/:id
• PUT /agreements/:id
• POST /tickets/:id
• PUT /tickets/:id

For example, a help desk could implement URLs like the following to perform their ticket sharing actions:

• POST
• PUT
• POST
• PUT

NOTE: This example is intended to be vague. For more detailed information read the full ticket sharing API specification.

Zendesk implements both sides of the API. Zendesk can send ticket updates to partners that implement the ticket sharing API. Zendesk will also receive tickets and ticket updates under our base URL.

Instead of digging into our database and moving records around, now we publish ticket updates to API endpoints that our servers implement. Any other help desk can implement these endpoints and participate in ticket sharing!

Your web-app can implement ticket sharing

We have written an API specification, that any help desk can implement.

If you run a Ruby-based help desk you can grab the ticket sharing gem we wrote and add it to your application. This should make integrating ticket sharing into your application much easier.

Take action

If you’re a developer, check out the source code on github or install the rubygem: gem install ticket_sharing.

If you’re not a developer, spread the word about ticket sharing. Send others a link to this blog post. Write a comment below and tell us what you think. Let us know if there is anything we can improve upon.

If you use a help desk other than Zendesk, encourage them to implement ticket sharing!