JSON or XML web services interface?

[kdangoor]

For a variety of reasons, I need a completely custom interface for our customers... that interface is not written in PHP. It looks like Cerberus had some kind of XML API in the past, but may not any more (as in in Cerb4). Is that correct?

[jstanden]

Hey there!

Yeah in Cerb3 we had a simple (non-standards) XML interface used by Workstation and Livehelp.

In Cerb4 we're planning on a RESTful interface on /cerb4/api which will support XML and JSON (specified by extension, in REST style).

We'd support most API functions, like: pulling ticket lists, retrieving a ticket, creating tickets, creating/reader contacts, running an F&R search, etc.

Work hasn't started on this yet, but it's just a simple plugin that wraps our PHP5-level API that already exists.

You can follow progress on this here:
http://www.wgmdev.com/jira/browse/CHD-417

Thanks!

[kdangoor]

How simple a plugin is it? (Or, more specifically, the dreaded question: "when might I have my hands on it?")

I'm currently testing out HelpSpot and Cerberus 4 and Cerb4 is out of the running because of the lack of a web API. The API is definitely one of HelpSpot's strengths.

Kevin

[jstanden]

From a technical standpoint, it's the simplest plugin that's been proposed on the forum in a month. All we'd have to do is decide what the REST API would look like (e.g., POST /cerb4/api/ticket/create.xml or GET /cerb4/api/ticket/FCX-12345-678.json).

Our Cerb4 code is cleanly organized into layers. The REST API would simply wrap our PHP API which is already done (you'd hope, considering the entire app is built on it!).

There are a couple other big requests I can solve with the web API plugin too, like Modernbill integration or people who want Fetch & Retrieve on their website. So it's certainly a priority.

I'm a little biased here, but I vote you stick with Cerb4. If you're worried about it getting delayed, just post a follow up here every day, or add me to your IM and do the same. ;)

I'll aim to get this going by the end of this weekend. You'll have to let me know the API calls you'd like to see and I'll do them first.

[kdangoor]

End of this weekend is quick indeed :)

I would need to be able to create tickets (including values for custom fields), update tickets and get a list of them (which status and description) for a customer, and get ticket details. Basically, I'll be putting up a customized front end for customer use. This frontend is customized based on the kind of support we're providing for a given customer.

It would probably also be useful to be able to create/retrieve/update/delete contact information, because our frontend app will also manage that.

Support staff would be working within the standard Cerberus interface, so I don't need think I need anything more than the above.

Thanks!

[jstanden]

Excellent! Thanks for elaborating. :)

Jeremy (former WGM programmer who's over at Yahoo! now) pinged me yesterday when he happened on this thread. The RESTful web API is something we have both wanted to see for a while, so we're going to go tag-team on it.

Your example, of essentially creating a specialized Support Center, is exactly what I hoped would happen in 4.0. It's actually the reason we originally launched the beta with no Support Center.

The Support Center as a disjointed thing doesn't make much sense. It should be a fluid part of your existing web site. The services Cerb4 provides are so much more interesting and important than the one-size-fits-all, pre-fabricated, public interfaces.

Getting the web API in place completes that. ;)

Thanks for the nudge!

[jstanden]

Just a quick update:

I built REST support (XML+JSON) into Devblocks tonight for one of our other products (PortSensor).

The commands for basic objects look like POST/create, GET/list, GET/#, PUT/#, DELETE/#. You send an XML payload like "<object><field>value</field></object>"

I wrote the code so it would be really easy to port to Cerb4. It should be absolutely no problem getting this into SVN by Monday.

[jstanden]

I've been wrapping up the authentication and privileges for the XML web services plug-in today.

I just need to wrap up ticket creation (with custom fields) and you'll have the basics. All the other ticket searching and address book management stuff is done and ready. :)

[kdangoor]

Hey, Jeff

That's great! Just what I needed. We're going to try to wrap up our eval this week (which is slightly complicated by the fact that I'm out of town the last half of the week). Having an API in place is a good step.

One suggestion: having a JSON payload on the way in would be substantially more convenient. My client for the API is in Python, and creating JSON structures in Python is as natural as it is in JavaScript. Whereas XML is more of a pain (as it is anywhere else :)

Thanks for getting this together so quickly!
Kevin

[jstanden]

Hey Kevin!

Dan@WGM and I talked about handling JSON on the incoming payload -- it shouldn't be a problem at all.

We'll just translate either XML or JSON to a generic format (nested PHP arrays or anonymous objects) depending on the URL extension of the PUT/POST (.xml or .json) or the content-type header of the request (text/xml or text/javascript).

I'll also add a couple more commands to the Web-API tonight: parse raw email, F&R, Overview, etc.

If you look at a recent build from SVN (505+) you can go into Config->Plugins and enable the "Web Services API" plugin. Click 'configure' on the plug-in once enabled and you can generate access+secret keys and set permissions for the key (allowed objects, read/write, IPs, etc)

Thanks for the feedback!

[kdangoor]

I made a web services layer a year ago for TurboGears in Python... once you build on an intermediate layer, you can really support any kind of transport you want. JSON is definitely a lot easier, so I'm happy you're making the switch!

A couple people I work with will be evaluating the Cerberus UI to see if it meets their needs, and early next week I'll take a look at the API (I'm off to a conference tomorrow).

Thanks again for the quick work. Sounds fabulous, and it looks like it'll meet my needs and your own!

Kevin

[kdangoor]

I'm finally getting a chance to look at the API now. While some docs will be helpful, I can likely piece some things together from the source. That said, can you explain how authentication is supposed to work? I'm sure I can figure it out, but I'm also sure that it would take you less time to tell me than it would for me to trundle through the code for the answer.

I have my access key and secret key generated, but I'm not sure how they're supposed to be passed along. I was starting out trying to do just a simple GET in my browser to see what happens.

Thanks!
Kevin

p.s. the checkbox in the configuration screen is not labeled as the "delete this key" feature :)

[neenach2002]

I think you need to do a POST, but let me check the docs right quick! ;)

Okay, here's the only docs that are done so far! http://wiki.cerberusdemo.com/index.php/Addresses_%28Web-API%29

[kdangoor]

Ahh, I figured I could GET the data if I'm not changing anything. I thought my trouble was with authentication, but it's always possible that GET vs. POST was the real problem.

By the way, at this point we're almost certainly going to go with HelpSpot over Cerb4, so the pressure is off on finalizing this now for me. It did sound like the API has value for Jeff and others, though, which is good.

[Kevinmiam]

Does someone have a code snippet of how to use the API for cerb4?

That would help greatly!

Thank you in advance!

[neenach2002]

Unfortunately, it's not done yet. However, there should be docs once it is.

[jasonabate]

Is there any example code on the web api for managing tickets? I'm looking at connecting Cerberus to a custom web application that I've built, and need to be able to let customers submit tickets through my UI (including immediate feedback on their ticket # for future reference) as well as provide them a display of current open and past tickets that they can click on and review the full ticket.

The database scheme looks clean enough that I'm sure I could find a way to do this directly, but would really like to avoid that (and the inevitable problems that will arise from it). Is there functionality in place now to support this (even beta code), or plans to support this in the future?

Thanks,

-jason

[neenach2002]

Is there any example code on the web api for managing tickets? I'm looking at connecting Cerberus to a custom web application that I've built, and need to be able to let customers submit tickets through my UI (including immediate feedback on their ticket # for future reference) as well as provide them a display of current open and past tickets that they can click on and review the full ticket.

The database scheme looks clean enough that I'm sure I could find a way to do this directly, but would really like to avoid that (and the inevitable problems that will arise from it). Is there functionality in place now to support this (even beta code), or plans to support this in the future?

Thanks,

-jason
As I said, it's not done yet - however, it will be soon and you will be able to do pretty much anything with tickets (including custom fields).

[jasonabate]

As I said, it's not done yet - however, it will be soon and you will be able to do pretty much anything with tickets (including custom fields).

Excellent, looking forward to it. If you need anyone to try it out, let me know - I'd be happy to assist.

-jason

[Hildy]

Please see http://cerb4.com/forums/showthread.php?p=4190 for an update on the REST web api.