Video and Slides: Is your API naked?  API Platform and Ops Considerations »

Thanks to all that attended last week's API Best Practices Webinar #5 "Is your API Naked? API Platform and Operations Considerations" (and thanks to our presenters @gbrail and @landlessness). Video and slides are below.

Our next API webinar, "Your API Sucks!  Why developers hang up and how to stop that" with @landlessness and @earth2marsh, is June 14th at 11am PST (sign up here!)

(And you can see all our API best practices webinars to date here)

Do you need an SDK for your API? »

In our last couple API strategy workshops, we've had good discussions on a common question for API providers - do you need to offer an SDK (software dev kit) for your API?

In this context we defined an SDK as going beyond offering an API to include platform-specific code that developers use in their apps to invoke API operations, also including the source code, and documentation that developers might need. Here's what we came up with:

Reasons to consider an SDK:

Speed adoption on a specific platform - for example Objective C SDK for iPhone.  Lots of experienced developers are just starting off with objective C+ so an SDK might be helpful.

Simplify integration effort required to work with your API - If key use cases are complex or need to be complemented by standard on-client processing. 

An SDK can help reduce bad or inefficent code that might slow down service for everyone.

As a developer resource - Good SDKs are a forcing function to create good source code examples and documentation.  (See some good examples here and here. )

To market your API to a specific community - you upload the SDK to a samples or plug-in page on the platform's exisitng developer community.

Reasons you might not need an SDK:

If your API is designed for adoption -  standards-based, well documented, etc.. developers may be able to get rolling without a client SDK.

Resources - it's tough to do a SDK for each platform you target, you'll have to pick carefully. Also, it can be time consuming and expensive to create SDKs (tip: maybe packaging up internal samples or test cycles can kickstart things)

Maintenance and versioning - convincing clients to upgrade to the newest version can be rough. Also, capturing the "local flavor" of each language you support can be a challenge.

Complexity -On each platform there might be use cases you don't expect, like keeping application-level secrets off clients, debugging, etc.

More is not necessarily better - fewer, more well-documented, code-level samples can often be the best resource. Facebook provides Android, C#, iPhone, JavaScript, PHP, and Python libraries (all documented differently), but Twitter supplies none. Facebook has more resources but still struggles a bit at times.

Our view: whenever possible, forget the SDK, and spend the time making your API better and more useable, and give good API resources such as example code.  

Agree or disagree? 

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.

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.)

Considerations for ‘open data’ API programs »

In my last post I wrote about how the book digitizing effort is trying to monetize underutilized books online.

For anyone contemplating exposing data or capabilities via APIs to create new revenue streams, there are some important implementation lessons that can be learned.

Have control

In Norway’s Bookshelf project, their free online books can only be read online and only in Norway, and cannot be downloaded or printed out. Similarly, with APIs you need to have a way to control who can access your data and from where. API Identity, API authorization and other API security considerations are a must.

Make it (at least something) free

Google must operate under copyright laws, but it has found a way to freely expose extracts or snippets under ‘fair use’. Similarly, you cannot expect uptake of your content or capabilities if some of it cannot be consumed easily and en gratis. Give at least some of what you offer away for free to spur adoption. Technically, this means being able to control what can be consumed at a granular level.

Get started!

Google, Bookshelf, and Europeana have ideas about how they’ll monetize books they put online, but they are still experimenting with the right business models. Executives shouldn’t wait for an iron-clad business model to present itself… you won’t figure out the right model unless you are ‘in the game’.

If you build it will they come? Developer Community and Audience »

(The 10th installment in our API Roadmap Considerations series)

You've built a great API and have the operational bases covered.  Now the fun part - buiiding awareness, adoption, and community.

Think about it like throwing a party - you need to get the word out, have food and drinks covered, and help people mingle.

That is - 3 things need to work together  - audience, tools, and community.

(But first you must have a cool product.)

Always loved this talk by Dave McClure.  First – your product better be cool. Or..start with a great, differentiated API.

Developers will make or break your API strategy. If you focus on making developers successful you are building on a very strong foundation.

It's important understand different developer segments, what's important to each, and key contributors. And there are thousands of APIs now - maybe dozens in your vertical.  Is yours differentiated by features?  Better terms?  A SLA?  More data?

Get the word out: Audience

We often see API developer community plans that focus heavily on tools and building a 'destination portal'. 

But first - plug into existing destinations and communities.  You can sign up for most of these now, for free.  They reach thousands or millions of developers and they rely on your content and participation.  Examples include:

• API listings and resource communities like ProgrammableWeb.
• Vendor communities, like Microsoft's MSDN, Google code.   If these developers might use your API, you should be there.
• Platform communities like RubyOnRails or iPhone.
• Independent communities like Stackoverflow.

This also helps your search engine discoverability on anything related to "API + your business."  You want to rank well aginst similar APIs in Google searches.

All the fixin's:  Tools and processes

Just like a decent party needs catering and comfy chairs, you need tools and processes dialed in before your API launches.  Things like developer onboarding , developer key management, and integrations with the business (billing, compliance, etc.).   Dress rehearse these during the private alpha period so you can handle demand when it comes.   We often see teams that have licensed all the tools but haven't run the processes end to end - it's just as important as testing your API.

You'll need to make it easy for developers to find and help each other when working with your APIs. Blogs, documentation in wikis, code samples and app galleries are critical and easy to create. (most are free).   And again, not just the tools but dress rehearse the processes. (i.e. who's on duty for monitoring and responding to tweets and blog posts.).  For example, we love GetSatisfaction for Apigee.

For content and resources, code samples are consistently ranked at the top by developers.   You can use your own QA stuff for starters -  that they can incorporate in their own apps.

Take jackets and get drinks:  Community

If your API is easy to find and you have tools in place, you can tackle 'community'.   A book could be written about this, but successful communities have a hardcore group of developers that help each other be successful, an open dialogue with the API provider, show up at both online and offline events, and have at least one rabid, hardcore evangelist ringleader at the core that writes code with the API and seems to be everywhere.

The best community managers make it all about the developers – welcoming them, showcasing their work, and making them stars.  (more ideas at the end)

Should you outsource community management?  It's all about the passion - we usually see the best being full-time employees that actively seek out the position.  

Your Roadmap: Audience and Community

So if you are opening and API, think about the following for your roadmap.

Audience and distribution

• Can you get awareness and distribution through existing developer communities, such as any vendor (MS, Google IBM), Platform (Ruby, iPhone), Independent, Directories (programmableweb)
• What Web marketing - Search Engine Optimization or Adwords - can you do to make sure developers find you

 Tools and processes

• Do you have formal documentation? Can you put it on a wiki?
• Do you have code samples on how to use the API?
• Do you have a place for developers to put their own code samples and showcase their own work and sample apps? (widgets, mobile apps, etc.)
• Are code libraries needed for important platforms? Should these be open source?
• Do you have a blog for best practices and a way to get in touch with developers on important changes (such as API version updates?)
• What about adding and managing developers?  More on that in User Onboarding and Management

Community management

• Should you have a dedicated full-time employee to drive community and evangelize your product and best developers?
• Are there any offline events or meetups you should be at?
• How can you recognize and promote your hardcore community members? Do you have an evangelist that knows these folks personally?

Good resources and other ideas

Create discussions & docs on Google Groups.  Check out how some of the great developer communities use Google Groups, like:

• twitter - http://groups.google.com/group/twitter-development-talk
• iphone - http://groups.google.com/group/iphonewebdev
• ruby on rails - http://groups.google.com/group/rubyonrails-talk
• get started with your own group here:  http://groups.google.com

Make your API sample code available on a social version control system like:

• github - http://github.com/ - uses git
• beanstalk - http://beanstalkapp.com/ - uses subversion

Promote Yourself on facebook, twitter & a blog

• facebook.com - create a fan page
• twitter - look for people doing the stuff with your API and call it out
• blogger, typepad, etc all provide a great way to respond to and showcase developers

(and thanks to Richard0 for the photo..)

Do you need API keys?  API Identity vs. Authorization »

(This is part 3 in our series on "Is your API naked? 10 API Roadmap considerations")

We’ve seen very few API providers with a completely open API – almost all employ at least one of these:

• Identity - who is making an API request?
• Authentication - are they really are who they say they are?
• Authorization – are they allowed to do what they are trying to do?

Do you need them all?  Maybe not.  Some APIs only need only to establish identity and don’t really need to authenticate or authorize.

API Identity vs. Authentication - Compare Google Maps and Twitter  

Take Yahoo and Google maps – they are fairly open.  They want to know who you are but they aren’t concerned what address you are looking up. So they use an “API key” to establish identity, but don’t authenticate or authorize. So if you use someone else’s API key, it’s not good but not a serious security breach.

The API key lets them identify (most likely) who is making a API call so they can limit on the number of requests you can make. Identity is important here to keep service volume under control.

Then take Twitter’s API -  open for looking up public information about a user, but other operations require authentication. So Twitter supports both username/password authentication as well as OAuth. Twitter also has authorization checks in its code, so that you cannot “tweet” on behalf of another user without either their password or an OAuth key to their account. This is an example of an API that implements identify, authentication and authorization.

The “API Key” – do you need one? 

API keys originated with the first public web services, like Yahoo and Google APIs.  The developers wanted to have some way to establish identity without having the complexity of actually authenticating users with a password, so they came up with the “API key,” which is often a UUID or unique string. If the API key doesn’t grant access to very sensitive data, it might not be critical to keep secret, so this use of the API key is easy for the consumers of the API to use however they invoke the API.

An API key gives the API provider a way to (most of the time) know the identity of each caller to maintain a log and establish quotas by user (see the last section). 

Usernames and Passwords – again, see Twitter

With more sensitive data a simple, API key is not enough, unless you take measures to ensure users keep the key secret. An alternative is username/password authentication, like the authentication scheme supported by the vast majority of secure web sites. 

It’s easiest to use “HTTP Basic” authentication that most websites use. The advantage of using this technology is that nearly all clients and servers support it. There is no special processing required, as long as the caller takes reasonable precautions to keep the password secret.

Twitter simplifies things for their users by using usernames and passwords for API authentication.  Every time a user starts a Twitter client, it either prompts for the username and password to use, or it fetches them from the disk (where it is somehow scrambled or encrypted where possible). So here it makes a lot of sense to have the same username / password for the Twitter API that it used for the web site.

Usernames and passwords also work well for application-to-application communications. The trick - the password must be stored securely, and if it’s being used by a server, where do you store it?  If you are running an application server that uses a database, you already have solved this same problem, because the database usually requires a password too. Better application server platforms include a “credential mapper” that can be used to store such passwords relatively securely.

There is a lot we'd like to write about around security so we'll split this up into a couple entries.  Next time:  Session-based authentication, OAuth, SSL and WS-Security, and rolling your own.

Is your API naked?  10 API roadmap considerations (part 1: visibility) »

We'd like to run a short series on product and technical requirements you might consider for an API roadmap or strategy.    We’ll base this on trends we see in talking to hundreds of product and engineering managers that are either opening or consuming APIs (or aggregating and publishing large numbers of RSS feeds.)

Instead of talking about your APIs functionality, this is about what's *around* the API features and data.  Many APIs start out as just raw naked back end features. And there is often a big gap between a raw feature and a full-fledged service, which is your API might eventually become.

So this series is about what's needed to "monetize", "productize", or "operationalize" an API.  And not just if you are providing an API to customers – much of this applies if you are consuming APIs as well.

Topic #1: API Visibility

We're always surprised how almost every company we talk to says how little they know about their API traffic and usage.   We see lots sifting through web server logs to understand usage. As the API becomes more strategic and you want to make the case for more investment - this gets more painful.

This happens a lot when an API starts as an experiment, launched by the 'ask for forgiveness, not permission' types (you know who you are).  Things like metrics or analytics are back burner until an API either gets off the ground or doesn't.

But most APIs usually end up getting more important more quickly than expected, and as a product and engineering manager you may start asking:

Who is using the API and how much are they using?

• How many clients, apps, developers are out there?
• How do they break down by type, region, class of service?
• How does usage map to existing customer or partner organizations. Or how do developers map to applications map to customers?  (This can be tough with only key or IP based tracking.)
• What parts of the API and service are they using - on a method or operation level?   
• How does traffic breakdown between the your own products and 3rd party products?  (If they use the same API.)
• What the aggregate and per developer/app/customer transaction and data volumes?

How fast and 'good' is your service? 

• What latency are customers experiencing, by developer, customer, region, or operation?
• Where are errors and user experienced bugs happening and how often? 
• How is the API delivering vs. any formal SLA have agreed to or paid for?
• How can you find out if a customer is having a problem (before they call you)?
• How is the API usage impacting the rest of the platform or web products that also use the same API?
• Can you quickly trap and debug based on a specific message? Based on what is in a cache? streaming right now?

How does the API impact the business?

• Who are the top priority customers?  Developers?   Partners?  Who should you call to up sell to a higher service tier or do a deal with?
• What do you need to show general management to make product strategy (or tactical) decisions?
• Will you need to create audit trails or metering reports for partners that are paying for API access?
• Do you need to create metrics based on a certain data value in the payload? (Such as a specific product SKU)
• What is the cost of the data that you are serving up? (if you are licensing this data)
• Are you in line with all the compliance standards that IT enforces for the on-premise apps?

Knowing this stuff is really important when opening an internal service as an API, because now customers, contract terms, and compliance regulations come into play.  Analytics and metrics help you get proactive with customers and partners, and are critical when you need to make the business case for an APIs to executives.  You probably use web analytics to help you improve your Web UI - at some point you need this for APIs as well to see where to invest.

What's your experience?  We’d love to hear what you think.  Next up: traffic management.