Thoughts on API Best Practices API Management and Infrastructure Blog

Where will your customers be this Christmas?

Keith Morrow has a great article on TechTarget series on how an API can create a disruptive impact on a retailer's ability to reach customers beyond traditional web browser channels.

One key point is that an API can be driven by a relatively small team. 

Yet an API has a disproportionate impact on the business, and this impact scales with low marginal costs.  

This can be an especially effective strategy for retailers that might live in world of thin margins, limited resources, and the constant pressure of the peak holiday season. 

For more on Keith's retail API experience, we commissioned him to write a Retail 2.0 API Strategy whitepaper discussing Retail API opportunities, challenges of launching with tight resources, and best practices.

You can download the whitepaper here.

API Scalability: Cache large ‘chunks’ in the API response

Highscalability.com has an interesting piece on caching as "secret sauce" for good web performance.

Facebook and Twitter are cache assembly lines -- every web page and API request is served up by many calls to various caches at different levels - assembling the final result from many different chunks. At this scale there is almost no other way to deliver reasonable performance.
 
For APIs - what's the largest chunk of all? The entire API response.

APIs lend themselves nicely to caching responses because it is often easy to identify the cache key. If you follow the REST pattern each URL maps uniquely to a resource that has a well-defined lifecycle.

If you're working on the next Twitter, you will need many layers of caching to deliver great performance, including the filesystem and database caches, and then you will add additional caching layers using products like memcached or Coherence.  But a final tier of caching for the API responses themselves can only help performance, so consider:

• Can API analytics data show the most common or slowest API calls?
• Are there slow API calls that return the same data over and over?
• Can you design using a REST pattern to make it easy to identify individual cache items?

There are a number of ways to speed up calls that are caching candidates, such as memcached or something similar.

Another way is to use an API proxy. A proxy that is sitting in front of your API servers is an efficient and easy way to add an additional caching layer without making any changes to the server tier. We have helped a number of customers drastically improve the performance of their APIs by inserting such a caching tier without touching the clients or servers. 

And caching isn't just helpful if you are building an API. Applications that consume APIs, whether they are running on another web server or on a smartphone, can set up their own API proxy so that responses from many devices are cached in a central place, even if the APIs that the application is depending on can't be depended on themselves to return good performance.

(thanks to jules:stone for the photo!)

API Versioning Hell? Think API Virtualization

We've seen an architectural pattern emerge over the last two years that deals with the expanding variety of computing devices and the exploding number of APIs used in modern applications.  This pattern is API Virtualization - applying a virtual layer above the API itself to deal with the different concerns that come into play when delivering an API to different device and machine endpoints as well as across a range of different classes of business relationships.

Sam Ramji gave this presentation at GlueCon as a Prezi.  The prezi is available here, and we've put the audio with it in the screencast below.

One of the big shifts that has occurred in application development is the move from libraries to APIs for use of pre-written code.   APIs enable access to not just logic but data and the the computational power required to render that data appropriately.  The Facebook and Twitter APIs are good examples of this, but there are many more including Paypal's X.com, Ebay, Amazon, Netflix, Sears, Blockbuster, Best Buy, MTV and Google. 

While applications like Siri which use 20 or more web APIs are still unusual, most applications use several APIs to deal with access to content, social networks, events, identification, payment, and other concerns.  These APIs change frequently, as do the applications that consume them, resulting in a web of dependencies and causing chaos in the development lifecycle.

API Virtualization enables these different concerns and dependencies to be isolated from the application or API provider, resulting in a cleaner development process and higher-performing applications.

Darwin’s Finches, 20th Century Business, and APIs: Evolve Your Business Model

What do APIs have in comon with Darwin's observations on evolution, the 20th century garment district, and the Kobayashi Maru?

Sam Ramji makes the case for APIs in his much written about web 2.0 talk  - watch and listen to the full talk or just flip through the slides - both below.

Retailer Markets Moving to Open APIs

When one of the largest, most successful retailers on the planet makes a move, you can definitely consider it a confirmation of a trend.

Last week, the WSJ reported that Wal-Mart is opening smaller-format stores in new urban locations.  Wal-Mart CEO Mike Duke stated in their annual report that their growth will be driven by “innovated new formats”, which includes the smaller stores and stores with drive-throughs for picking up internet purchases.

Essentially, Wal-Mart is going to where their customers are…. taking their brands to different chnnels where customers spend their time, to be there when those customers want to buy.

What does that have to do with APIs?  Everything.

Retailers as diverse as Sears, Netflix, and BestBuy are opening APIs to take their brands and their services to where their customers spend time.  Those customers are on Facebook, on Twitter, on enthusiast sites, on their iPhones, iPads, Xboxes, etc. 

As the image below from Sam's Web 2.0 talk depicts - you may have to connect to customers across many diverse channels, from smartphones to Xboxes to your car and kiosks.)

Getting your capabilities into these environments where customers are spending time requires that you fit into new formats… like an iPhone or Android app, or an iPad or Xbox app.  You can’t possibly be an expert in the dozens (hundreds?) of platforms, sites, and devices out there.  Developers can help you do that, if you have your catalogs and services exposed via web APIs.

By the way, we have a new whitepaper out on Retail 2.0 today, you can get a sneak preview here.

Working over vendors:  A buyers guide for API management

The explosion of APIs is driving companies large and small to launch APIs for their customers and partners.  But both public and private APIs require management features well beyond their internal functions.    How should you approach the 'build vs. buy' analysis and evaluating API management solutions and vendors?

As a former CTO that has recently gone through this process, here are some lessons learned on how to scope out requirements, evaluate and select a solution.

Know the problem (and requirements) you are solving for

Many API product managers are initially tasked to spec out only a small slice of the problem (such as "get me a developer portal"  or "we need developer analytics."  ) Your requirements landscape is likely much wider than this.  Make sure your PM thinks about business requirements that have technology implications in areas such as:

1.    Security, Access Control - Authentication methods
2.    Reporting, Analytics -Usage by developer, organization, API, location
3.    Threat Protection - Denial of service attacks
4.    Traffic Management - Routing needs for versioning, operations management
5.    Mediation, translation - Protocol bridge between SOAP, REST, JMS etc
6.    Performance, Scale -     Clustering, caching
7.    Developer support-     Access key management, FAQs, wiki
8.    Operational support - Root cause analysis, logging

(For more on these topics, see this blog series)

Get everyone involved, early.

Because APIs touch partner relationships, they are critical to the business, and there are multiple stakeholders in your organization.  Walk through the lifecycle of an API, what roles support the release of an API, external access, operational support and management. These stakeholders should be represented in the overall product management strategy and accounted for in your requirements for API management.

Considering a vendor? Demand a POC!

The requirements, operational view and deployment strategy will provide an outline of scope for build vs. buy considerations. All of these functions should be outside of the core elements of the APIs themselves to ensure consistency without duplicating efforts for key policy areas that are needed for your APIs.

If you engage an API management technology vendor, these requirements can be prioritized and used to drive a demo of a solution to ensure the capabilities meet your needs. Insist on a POC (proof of concept) for a deeper dive and validation of more technical requirements.  This exercise will quickly allow you to determine commercial solutions that have the potential to meet your needs and provide a concrete plan for demonstrating capabilities that are of material value to your organization.

A POC will tell you a lot about a vendor -  both what they would be like to work with on a day by day basis and how they meet their commitments.  A POC will also tell you how well your own team has thought out what they need and how prepared they are to execute it.    Eliminate vendors that will not step up to a POC.

Also,  make sure your own team goes back and can repro the POC -  without the vendor.     

This diagram below (and a larger version here)  shows how we thought about our POC process.

Revisit the priorities and rollout strategy for API management

This evaluation process should expedite the short list of vendor options that will satisfy your needs and as well as gain internal consensus on what API management means to your organization. You may find the depth and breadth of your requirements will motivate you to find a commercial solution rather than build your own system that will have to be maintained in addition to your core APIs.  

A key consideration for the solution you select is handing ongoing changes after this system is deployed. Once your APIs are operational you’ll need a way to manage updates to numerous policy areas on a regular basis and most likely you will want to avoid any downtime to implement those changes.   For example, my previous role, we did an cost analysis of how many independent API codebase versions we could support at one time.  Our answer?   Two.   This drove us to select an API management technology to  provide a versioning and mediation layer above the API layer.

It is important to review the flexibility of the system to avoid limiting your API management capabilities and practices to a particular solution.

Operational awareness

Policy enforcement is typically the initial area focus for API management but operational visibility is also a key area to focus to include as well. How will you report on usage and do you have a consistent way to collect data to be aggregated? Do you have a common root cause analysis process to enable message level tracing and logging regardless of the API?

Conclusion

The topics around API management are numerous and not unlike the questions that were contemplated during web browser adoption. With a new delivery model of information and services there are multiple stakeholders to consider during a ongoing lifecycle of development and operations.  Developing an understanding of your needs up front will greatly streamline your selection process as well as get a common understanding of what API management entails within your organization.

Darwin’s Finches, 20th Century Business, and Open APIs: Evolve your Business Model

Today @sramji was invited to speak on API business models and strategy at the Web 2.0 Expo in San Francisco.  

Thanks to our customers and many others for these API best practices and ideas.

Don’t try to market to developers.  Instead, solve their problems.

Not long ago you could count the number of 'developer marketing' programs on one hand.  Now there are hundreds of programs as Web companies and enterprises open APIs.   These companies know that developer adoption will make their API strategy succeed or fail.

But Developer Marketing is an oxymoron.  Developers hate marketing.   

You cannot drive adoption by 'marketing to developers.'  Sure, you can send offers to your developers but your mileage may vary.

A better formula - understand what's important to developers and give them what they need to reach these goals. Developers want to:

•  build new skills that lead to the best projects and jobs.  This is why new or proprietary tools and programming models are tough to get off the ground - it's a small market of new projects for the developer.
•  increase their productivity.  With good tools and by connecting developers with decent resources and each other for help.  This is why sites like StackOverflow take off. 
•  be recognized for good work and see their products used.  Focus on showcasing their work, not your product.  It's not about you.
•  get paid.  Think App Store model, or affilate marketing networks.

Talk to the folks that made the big developer networks sucessful and you'll hear these points over and over. Some others:

• Developers are not buyers, but are very strong influencers.  There are superstars in the developer world - make them fans and that is the best marketing you'll ever get.
• You can't 'own' or 'use' developers because they have an account on your service.  Developers have lots of options and switching costs might be low from your API.
• Act on their feedback.  Developers are smart and listening and acting on their complaints and ideas is critical to your credibility.
• Developer communities are fragmented.  For example, there is no such thing as an "API developer', but instead there are Twitter or Facebook or Salesforce developers.

Once you have attracted a developer to use your service - they are like gold.   So treat them with respect - don't try to 'use' developers or you might lose them!

OAuth is improving, but still moving

We've been following the fast-moving debate in the IETF regarding OAuth 2.0.  OAuth, for those of you who have not encountered it already, is a set of authentication technologies for the Internet designed around the concept of an access token.

Access tokens, in the words of Eran Hammer-Lahav, are like valet keys -- they give the holder access to a specific function, for a specific amount of time. For instance, you might use OAuth to give another web site the ability to read photos from your Flickr profile, but not to modify them. OAuth lets you do this, it lets you go back to Flickr and revoke the web site's permissions at any time, and it does it without requiring that you give the site your Flickr password.
 
The current spec, OAuth 1.0a, is implemented in lots of places, and it solves a lot of problems. However, implementing it is no picnic for either the API provider (the server) or for the developer who builds the client. (There are libraries, of course, not to mention products such as our own that simplify this process.)
 
OAuth 2.0 introduces many changes. The most important is that a client may now use a "bearer token." That's a fancy IETF way of saying that an access token can just be a string that the server gives you. On every request, the client passes that token back to the server, the server checks to see if the token is valid, and you're done. This is much simpler to implement than OAuth 1.0a, but it is only secure if you use SSL for every request. Applications that won't or can't use SSL may still use the old way of transmitting each token, which encrypts the token so that it is safe even if SSL is not used or even if it is intercepted by a proxy like Apigee.
 
However, OAuth 2.0 is far from complete. It is currently undergoing lots of discussion on the IETF mailing list, and the spec draft changes daily.
 
That's why I was surprised to read today that Facebook is using OAuth 2.0 to authenticate its own API. Now, some of the key players in OAuth work at  Facebook, and they have chosen to use only a part of the spec, and the part that's arguably the least complicated. I'm sure that they feel that taking this calculated risk now is in the best interest of Facebook and its developer community, but the possibility remains that the spec will change and Facebook will have to change its implementation to match.

(In fact, at the moment I write this, they do not -- the name of the query parameter that holds the token is "access_token" in the Facebook documentation and "oauth_token" in the latest version of the spec repository.)
 
In the meantime, developers building on top of these APIs may have to contend with OAuth 1.0a (the current spec), OAuth 1.0 (an older version that some sites may still use), the draft form of OAuth 2.0 as implemented by Facebook, and even "WRAP," which introduced some of the concepts used in OAuth 2.0.
 
So the good news is that there are lot of good standards being written that can make it easier to produce and consume powerful and secure APIs. The bad news is that those standards are still changing. So stay tuned, and be careful!

Right product at the right time:  API Product Management

Recently we were asked by a SaaS company exec "can't we just hire someone to come in here and build our API for us?"

Danger, Will Robinson.  Just like any other product in your stable, your API needs to go through your product management practice.  Successful APIs usually have a dedicated API product manager that creates the 'right product at the right time" by continually focusing helping the team stay on target by driving:

1. What is the vision for the API?      How do you go from an idea to great product?  Start by asking what is your vision?  if you were sitting around with your top 5 execs..would they agree?   One good PM framework we've seen really focus an effort is explicitly defining the "VMSO" or "Vision, Mission, Strategy, Objectives" before every major release.  For example:

• Vision - what is "the dream" (example: be the most widely used widget catalog on the planet)
• MIssion - what do we do every day to achieve the dream? (example: have the easiest catalog API to learn and use)
• Strategy - what is our unique approach for achieving our mission? (example: have the smoothest sign up, clearest REST API and best community support)
• Objectives - what are our 1-3 key API metrics to determine if the strategy is working? (example: developer apps, API transactions, API revenue)

2. What is the target customer segment for the API?  Mobile developers?  Your top 10 partners? Affliate marketers? Each segments may need different features, policies, or marketing approaches. Do a customer or developer segmentation analysis and force rank priority segments. 

And if you ask your API team who their target segment is and the answer is 'everybody' - get worried.

3. Develop use cases.  Ask how little, not how much, you can launch with your API.  Taking back functionality is difficult once it's out there.  Identify and prioritize the minimum set of use cases (or user scenarios - such as 'browse catalog information')  and consider throwing out anything outside what's needed for each use case.

4.  Iterate quickly.  It's rare to find a successful API program where the PM doesn't say something like "and after we launched our customers took us in a completely different direction." Consider agile development techniques to help your team iterate quickly. 

5.  Differentiate your API. How is your API or content different than competing APIs in your vertical?  Why should I drop what I'm doing now and use your API?  Using a well-worn PM 'positioning framework' can help the team agree on this beforehand. For example:

What other PM processes do you recommend?

(and thanks to respres for the great photo.)