REQUEST A DEMO

Using the web APIs in Dovetail Bootstrap

Kevin recently blogged about Dovetail Bootstrap, a free, sample application which helps Dovetail SDK developers get up and going and creating web applications quickly.

 

The code for Dovetail Bootstrap is open and available on GitHub. Feel free to watch, fork and improve the code.

 

One of the capabilities demonstrated in Dovetail Bootstrap is a web API – specifically the Create Case API. I wanted to do a quick walkthrough of calling this API.

 

Wikipedia has this to say about Web API:

A web API (Application Programming Interface) is typically a defined set of HTTP request messages along with a definition of the structure of response messages, typically expressed in JSON or XML. While “web API” is sometimes considered a synonym for web service, the Web 2.0 applications typically have moved away from SOAP-based web services towards more direct REST-style communications.

 

The example we’re showing here fits into this definition nicely. Simple, direct, REST-style interfaces.

Usage

 

Why would I want to expose an API such as this? How about a few examples.

  • We want to allow our partners to make requests to us that directly invoke actions in our Clarify/Dovetail system.
    For example, allow our partners to take a case from their CRM system, and send it to us, by allowing them to call the CreateCase API over the web.
  • We want to have a facebook application for submitting support requests that are pushed directly into our CRM system.
  • We want to allow our customers to be able to submit a support request from our website, and have that automatically create a case.
  • We want to be able to take a mention from our social media monitoring platform (such as Radian6 or Spredfast) and turn that into a case.
  • We want to develop an Outlook or Gmail extension that allows us to easily take an email and turn that into a case.
  • And a thousand other use cases…

 

In today’s day and age, APIs, especially those that can be called over the web, are essential to integrating applications. Clarify systems are no exception.

 

Let’s get into some specifics.

Create Case API

 

If you simply make a GET request (which your web browser will do by default) to the http://myserver/api/cases/createendpoint, it will give you a web page that can be filled in and submitted.

 

create_case_page

 

When that form is submitted (by clicking the Go button), the browser does a POST action, which submits all of the form data to the server, and the case is created.

 

Now, instead of using our web browser to submit the data, we can do it programmatically using an HTTP request. Pretty much any language out there can make an HTTP request. Java, .NET, JavaScript, Ruby, etc.

Just Curl it

 

One simple way to see it in action is to use curl, which is a command line tool for transferring data with URL syntax. We’ll pass in the data we want (Contact and Site info, case title, queue, and our authorization token).

curl -d "ContactFirstName=Mark&ContactLastName=Donahue&ContactPhone=515-345-9876&SiteId=1
&Title=Case title goes here&Queue=Support Cases&authToken=0c8612b21afc40c880962e5db6bfd6b4" 
-H "Accept: application/json" http://myserver/bootstrap/api/cases/create/

 

Calling that from the command line returns the ID number for the case that was just created.

 

curl

 

Pretty simple, no?

 

Note that the result in a JSON format, as we specifically asked for JSON by specifying the Accept header to beapplication/json.

PowerShell

 

If you follow me at all, you know I dig PowerShell. So here’s an example of a PowerShell script that makes a request to the CreateCase web API and prints out the result.

 

C# example

 

Kevin recently shared an example written in C#. The data elements posted are slightly different (as it’s  using a customized CreateCase API), but other than that – it’s the same.

What about customizations?

 

Of course, everyone has customizations they want, especially when creating a case. Maybe you want to set some custom fields, or set the case type to something specific, etc.

 

No problem – that’s why we give you the source code for Dovetail Bootstrap – so you can customize it any way you want.

What if I don’t want to customize it myself?

 

Not comfortable customizing it yourself? No problem, our Professional Services team can work with you on an engagement to get exactly what you want.

 

In fact, we’re working with one of our customers now on this exact scenario – adding some specific customizations around the CreateCase web API.

 

We can either do all the work for you, or pair with your developers so that the task gets completed, and your developers also learn how to do it themselves.

What about other APIs?

 

As I mentioned earlier – Dovetail Bootstrap is an example application, meant to help get you going. You can follow the pattern that we use for the CreateCase API to use any of our other APIs – or even write your own.

Go Forth & Make Awesomeness

 

As the tools and technologies continue to become simpler and cheaper, it becomes easier and easier to make awesomeness. Now go!