11436 SSO

Beware One Way Streets: The Importance of Comprehensive API Queries

Brian Mulloy
Nov 27, 2012

In a recent blog post about revving the engine in your company's API Machine, @kevinswiber covered the importance of building mashup-friendly APIs. Another pattern that's important to the success of your API is comprehensive queries.

Crafting a delightful API and creating an enterprise database both require knowledge, talent, and a subtle design touch. Oftentimes, a database system is made for a specific business application. It might show which territories belong to a specific agent or which stocks belong to a certain mutual fund, or all the products purchased by a specific customer.

One-way queries

In large companies with big systems of record that have been around for decades, queries often go one way but don't work the other way around. What do we mean by that?

Symmetrical queries and the shift from a direct to an indirect value chain

As you prepare your enterprise systems for journey into the app economy, a key insight to keep in mind is that we are going from a direct world to an indirect world. That is, you won't always know who the app developers are or what apps they intend to build using your internal systems via the API. In this world, the goal for your API is to allow the app developer to access data in a secure, predictable way while enabling unpredictable creation of value.

A developer might see an opportunity to turn things upside down, to view and use your systems and data in new and innovative ways, which in turn takes your company's value directly to your target markets:

  • Along with knowing which territories a sales agent covers, what if the app needs all the agents in a given territory so that it's easier to render on a mobile map making it easier to manage the agents?
  • Along with knowing which stocks are in a fund, what if the app wanted to know all the funds containing a specific stock so that people sharing stock tips info on Twitter created more demand for mutual funds?
  • Along with knowing all the products purchased by a customer, what if the app wanted to know which other customers have purchased a product so that customers could connect on Facebook and promote the brand?

Developers and their apps need to explore all directions of curiosity and the best APIs facilitate that exploration so that their apps have more impact.

Here are a few examples of starting with a typical enterprise web service, morphing it into a nice web API, and then accounting for the symmetrical query.

Enterprise Web Service Web API Symmetrical Query

GetAgentTerritories(agentID)

/agents/{id}/territories

/territories/{id}/agents

StocksForFund(fund_id)

/funds/{id}/stocks 

/stocks/{id}/funds

CustomerProducts(acct)  

/customers/{id}/products

/products/{id}/customers

When you are designing your API, take a step back and ask yourself if the API is a two-way street? For every association in the API is there a symmetrical request that you could also provide to developers so that they create more innovative apps?

Along with creating easy grab data handles, providing a comprehensive API with two-way queries will make your API efforts succeed.

API Management Decision-Making Kit

Next Steps

 
 

Resources Gallery

News