11436 SSO

The Company API Machine: Easy-Grab Data Handles

Kevin Swiber
Nov 13, 2012

Inside nearly every company is an API Machine, a powerful engine that activates latent business value from enterprise systems and databases by plugging directly into the app economy.

Now is the time for companies to turn on the API machine. So, what's important? How do we learn from and avoid the now obvious mistakes that API pioneers have made in the past? How do we create an API initiative that maximizes impact and relevance?

We'll review the key patterns for success:

  • Easy Grab Data Handles
  • Comprehensive Queries
  • Support Mobile & Web Apps
  • Extensibility
  • Beautiful API Design

Let's get started with Part 1.

Easy-Grab Data Handles: Building Mashup Friendly APIs

So we have an API. Great! We've gone through many iterations and, as an API Team, we've decided exactly how our API should be modeled.

As we evangelize our API, we pick up a little steam and start convincing app developers to take a look at our awesome API product. What's the response?

"Well, I like your API, but I can't do anything meaningful with it. My app needs to mashup your data with data from other sources." 

- Anonymous App Developer

What our Anonymous App Developer is really trying to say is that we forgot to think about data compatibility. D'oh! That's a key characteristic of a mashup-friendly API. Luckily, there's something we can do about it. Let's look at a process for exposing pieces of our API model that can be used as data handles with great mashup potential.

Research Popular APIs

All artists need inspiration. To know which data hooks to expose, let's investigate the big players in API mashups. Google Maps, Twitter, LinkedIn, and Facebook are interesting candidates. ProgrammableWeb is a good resource to find what's hot in API mashups.

Look at the input fields these APIs need for requests. They provide hints that can help us along the way.

Data Handles

Service Data Handle Example
Google Maps Location Bangalore, India
Twitter Ticker Symbol $GOOG
LinkedIn Company Name or Ticker Google or GOOG
Facebook Products or Brands Nike


Find the Seams and Build in Hooks

Let's examine our own API. What bits of information can we tease out of our model and present in a way that makes our API mashup friendly?

We can hunt for good candidate fields. Based on our research, we already have some ideas. Here are some common fields we can use as data handles:

  • Location
  • Stock ticker symbol
  • Phone number
  • Industry code
  • List of keywords
  • Identification number

We can take the seams we found and use them to devise a plan for exposing the data handles our app developers will need.

As we start to split apart our model by revising the old and adding the new, we may need to take a trip back to the drawing board to ensure our changes are logical and our API is still cohesive.

This is a good time to loop in our app developers. As our primary customer for our API product, they will have great feedback as we iterate and improve.

Set it Free

It's time to release the new, improved API to our developer community and see what they conjure up!

As mashup popularity skyrockets, we could provide a gallery of cool and interesting apps that are now possible. The gallery serves as an inspiration to developers looking at our API for the first time.

This time, we modified an existing API, but this same process can be useful for greenfield API design, as well.

Check out Part 2 about Comprehensive Queries. Until then, happy mashing!

For questions related to this post or to show off your hard work, check out the API Craft Google Group.

Scaling Microservices