Integration 101 – How to Sound Cool & Talk About REST APIs Like You Know What They Are
There’s a lot of talk these days about integration via REST API’s. While it feels like everyone has agreed that REST APIs provide an easy means of integration (a good thing), it seems as though many business users still tune out the minute they hear “REST API,” quickly filing it into the “too technical for me to understand” category (a bad thing).
For those that have not heard the term before, a REST API is an integration method that provides a way for data to be sent from one system to another. You have probably seen countless examples of REST APIs in your daily life, whether it is a list of sports scores displayed on a website, a map included in an app, or the ability to post a Tweet from a 3rd party app. A very common example is using the Twitter REST API to display recent tweets on a Blog or webpage.
So while integration tends to be written off as a complex subject, I’d like to come clean and admit that anyone can understand how REST APIs work.
Who cares and what does this have to do with Gamification?
Two items on the mind of business stakeholders in nearly every gamification project are: cross-platform compatibility and speed of deployment.
Currently, most gamification programs require the ability to recognize users across a variety of platforms and devices. For example, users should earn points for checking in at an event on their mobile phone as well as for completing courses in an organization’s Learning Management System (LMS). By their very nature, REST APIs can easily receive calls from all of these various platforms and devices.
In addition to cross-platform compatibility, speed of deployment is another key factor in any project and, as we’ll see, the simplicity and ease of integration inherent with REST APIs ensures that the technical integration will not be the bottleneck in a project.
So what is a REST API Call?
A quick Google search of “REST API” will return nearly 9 million results that will go into far more detail about what a REST API is, how it works and where it came from than I would ever care to know.
For the purposes of this post (pun intended for any nerds that made it this far without flaming me), a REST API call is really no more complex than a URL that you have been using to navigate the web for years.
Yes, a URL such as http://www.bunchball.com/blog that you would type in your browser to check out the Bunchball blog. The only slight difference about these URLs is that they have additional data appended to them to pass data to the other system.
A closer look
Let’s take a look at a very common usage of the Nitro REST API – displaying a user’s point balance. In order to display a user’s point balance, this is the REST API call that we would make:
That’s it and hopefully it doesn’t look too intimidating, but let’s look at it piece by piece.
We start by specifying the location of the Nitro server: https://sandbox.bunchball.net/nitro/json. This is really the same as specifying http://www.bunchball.com/customers to look at Bunchball’s customers or specifying http://www.salesforce.com/customers/ to look at Salesforce.com’s customers.
Everything after the “?” is the additional data that we are passing so the Nitro engine knows what we are looking to do. Each piece of data is separated by an “&” sign.
In this example, we begin by specifying which API method we would like to call. In other words, what data would we like to send to or pull from Nitro? The Nitro API consists of approximately 100 methods that provide access to store and retrieve all sorts of user data. We provide detailed documentation about all of the methods and how each one can be used. In this example we want to get the User’s Point Balance so we use: method=user.getPointsBalance.
Finally, we only want to return the point balance for the current user, so we will also let Nitro know which User we want the Point Balance for: userId=bunchball (bunchball is our user’s ID).
That’s it. It really is that simple.
Since a REST API call takes the form of a URL, you can actually call it by copying and pasting it into a web browser. Before you try this with the URL above, I’ll let you know that you will receive an error. This is because I did leave out a few security codes that we also pass in with these calls to ensure that users are not gaming the system and that users are who they claim to be, but we’ll save those for the advanced class.
Hopefully this provides a high level understanding of what a REST API is and the form that a REST API call takes.