As I’ve talked about before, in our API documentation tutorial, documenting your API effectively is critical if you care at all about getting the maximum return from your design investment. It doesn’t matter if you are building a private API for a few selected partners or trying to build a company around a public API – poor documentation is going to sink your endeavor every time.

The challenge is that it’s really difficult to find people who are as great at documenting systems as they are at designing them. As a convenient shortcut, many API designers use tooling to auto-generate documentation. This often means exporting machine-readable interface description files like WSDLs and WADLs based on some type of configuration data entered into a development or testing tool. Assets like these are great for driving programmatic components on both the client and server side but they have limited value otherwise.

WSDL files, in particular, are popular in the SOA space because they allow client developers to auto-build proxy classes that can be invoked in the RPC style that is prevalent for SOAP-based integration. This advantage is diminished in the HTTP API world as we have moved away from this document binding style of interface to less structured forms of integration. But even putting this distinction aside, WSDLs have never provided an effective means of documenting SOAP systems and WADLs are no better.

Effective documentation implies effective communication. In the vast majority of situations, a standards-based XML description of your interface is not going to cut it. Application developers need to understand much more than the names and parameters of your API if they hope to build real applications in reasonable time-frames. This means you need to create documentation fit for developers – in other words, documentation built for humans.

Your documentation will act as a navigation system through the complexities of your API. Simply providing a WADL is the equivalent of providing a set of GPS coordinates to a tourist in your city. With the right tools, they may get there eventually but a human-readable map would provide a much richer and simpler experience. If you care about the developer experience for your API, you’ll spend some time and effort writing documentation that works.

The role of the business developer has traditionally been to initiate partnerships and follow through by ensuring some sort of integration is implemented.  As enterprises become more software-driven, integration itself increasingly comes through APIs.  This may mean that the implementation of API-driven “partner portals” is replacing traditional business development practices.  A recent article from Wired claimed that 70% of all jobs will be replaced by robots by the end of this century. Are APIs and partner portals the robots that will replace manual business development processes?

Here’s an example of how a business partnership might come about these days. Interaction with an online API partner portal will act as the initial “conversation” that leads to the partnership. If you want to integrate with Salesforce.com, you go to the Salesforce partner portal, figure out the relevant SDK/API, build an app and then submit it to the Salesforce AppExchange.  You don’t ever need to actually talk with anyone at Salesforce to become a business partner with the company.

Another example is the way many companies now enable access to their Web sites via Facebook Connect, Google+ Login or Twitter Login. This represents the first step towards establishing a business partnership with Facebook, Google or Twitter. It’s not new in the Web world and has been discussed for years. What makes it relevant to this discussion is the way it’s being applied to out-dated business processes and practices.

Great platform companies have realized this, “robotized” their business development processes and rationalized their business development teams. As robots are to manufacturing, APIs are to business development. Better technology means that we can focus our human resources on more valuable activities, since handshakes are now being made over OAuth instead of costly dinners and drinks.

APIs have multiple purposes inside an enterprise. Most of the early excitement around API stemmed from the potential for APIs to foster communities of “long-tail” developers. With data becoming the new mobile currency, opening up data to legions of developers held out the promise of multiplying revenue and reach for start-ups and enterprises alike.

While several start-ups have demonstrated the potential of tapping the long-tail developer community (look at examples like Twillio, Tapjoy, Stripe and Braintree) the number of enterprises that have seen similar success is less clear (Amazon Web Services is an obvious counterpoint).

One reason for this is simple – enterprises have conflicting interests and are almost never set up to successfully service these communities at all costs. This doesn’t negate the value of fostering relations with the long tail. External developer programs make sense for enterprises and should be viewed as strategic, even if the immediate payback is not obvious. With the advent of the app economy, developers represent as important a channel to market as traditional distributors.

However, often overlooked in the race to launch an external API developer program is the potential benefit of an internal API developer program. Enterprises have, in many cases, thousands if not tens of thousands of developers internally. Often, internal developers are supplemented by contractors. Enabling all these developers to become mobile innovators through APIs holds out the promise of delivering the kinds of leaps in productivity, agility and experimentation that will benefit any enterprise.

To make internal developers innovation leaders, it is essential to provide a canonical way for these developers to access all corporate application and data resources. An API abstraction layer delivered through an ESB or API Gateway simplifies the process of API-ifying information resources and consuming APIs.

But that’s not enough because developers will still need a central directory or registry of APIs to discover which APIs are available and what these APIs do. In the WS*-centered Web services world of SOAP-oriented APIs, which most enterprises still inhabit, this function would be handled by a UDDI directory and some accompanying “repository” software. But in the API world, no exact analog has existed – in part because every API Management vendor has insisted on provisioning its API portal in the public cloud only, a place most enterprises are reluctant to post APIs aimed at internal developers. Layer 7 aims to bridge the gap.

The Layer7 API Portal is the first turnkey API developer portal that can be deployed 100% inside a customer’s private cloud, datacenter or IT facility. Moreover, it is the first developer portal to offer simultaneous support for both RESTful APIs and SOAPy APIs, meaning it can act as a substitute for existing UDDI-style services while providing a pathway to newer RESTful services. Best of all, it can be implemented with different grades of privacy so that the same API Portal can support internal, contract and external developers at the same time – with each group seeing only what the enterprise chooses.

By centralizing where APIs are presented for discovery and consumption by developers, enterprises can make it easier for their service innovators to build new capabilities and mash multiple existing services into newer composite business functions. They can introduce new apps and applications faster. They can respond to change faster. They can build and iterate on new mobile apps in less time, with less error. It all comes down to the API presentation layer.

For close to five years, Intel has had a stake in the API space. All the while, I’ve often asked myself why. Intel originally acquired an API Gateway from a prior Intel Capital investment that never fully blossomed. And despite the oddness of having a tiny enterprise software franchise lost inside a semiconductor behemoth, Intel persisted in its experiment, even in the face of questionable market success and lukewarm analyst reaction. So, why double down on APIs now?

With the steady decline of the PC business, Intel clearly has to look elsewhere for its future growth. The cloud datacenter is not a bad place to start. Cloud server farms clearly consume lots of processors. Still, servers powering Web sites can operate fine without APIs, thank-you. But servers powering mobile is a different story. Mobile apps (whether HTML5, hybrid or native) get the data that makes them valuable from applications that reside in datacenters. And APIs are the key to letting cloud data be sharable with mobile apps.

Clearly, app-centric “smart” phones and tablets and TVs and cars and watches and glasses are changing the way we go about our daily business. And APIs will power these smart devices by giving enterprise and Internet companies a way to push their data to apps. That hope of bridging the cloud with mobile is probably why Intel has kept its current API product intact. Mashery broadens Intel’s API scope by providing a way to not only share data with mobile apps but now also the developers that build these apps. But will this plan succeed?

If it does, it will take quite a bit of time. The reality today remains that Intel – even despite the semi-recent McAfee acquisition – is not oriented to selling software or even cloud services into the enterprise. It’s missing the sales force. It’s missing the history. And in many ways, it’s missing the rest of the software stack it needs to power the networking, infrastructure and application parts that underpin data in the cloud. That will make selling an API platform comprising a legacy API Gateway and newfound API developer platform a harder proposition. It’s kind of out there alone.

Another obvious roadblock to making the Mashery acquisition successful is that Intel’s existing API Gateway and the Mashery API service are designed for two very different audiences inside the enterprise, with un-reconcilable needs. The API Gateway is designed for an IT department that wants to run its API Management layer in its own datacenter. The Mashery offering is designed for a non-IT buyer (a mobile program manager, say) who wants to run everything in someone else’s cloud.

One is technical, the other is not. One is on-premise, the other is SaaS. One sells traditional software licenses, the other pure subscription. The first aims to address internal and external API integration challenges. The latter is only really concerned with the challenge of acquiring external API developers (though Mashery would probably protest this point).

Will the two be a marriage made in heaven? Given that the Intel/Mashery partnership is already a year old and that Mashery was barely able to grow its revenues in that time, the likelihood seems remote. But who knows for sure? And anyway, Intel has probably not bought Mashery for its $12M in revenue but for its long-term potential as a pathway to mobile.

I often hear the term “ROI” used in reference to an API program. Often, it is the discussed in the context of getting either direct revenue from an API or growing reach from an API, which in some places, translates into a lower cost of customer acquisition. While both direct revenue and reach are admirable goals, ROI from an API program is not limited to the number and quality of external developers.

For instance, most organizations will derive far more immediate payback from an API initiative if it enables internal developers, enterprise mobility initiatives, tighter partner integrations or even IT rationalization through hybrid cloud. Each of these endeavours will pay dividends in terms of productivity, agility, distribution and lowered IT costs. Each deserves its own dedicated discussion. However, underpinning all of these API business drivers  – external developers included – there is one often-overlooked consideration for cost and return in any API program: how do you introduce and innovate new APIs cost effectively?

Obviously, there are many ways to stand up an API. Many packaged software applications have some kind of API already, even if some are XML- or SOAP- centric. But in many instances, nothing exists except the desire to expose a piece of functionality or quantity of data as an API. Programmers can obviously build “programmable  interfaces” onto almost anything. It just takes time and people. However, the results will be brittle and the journey expensive.

A faster, less costly and more flexible route is to use an adaptation layer that can talk to various application or data backends and dynamically render one or more as an API. Using a backend adaptation layer can, with the right product, also solve the related problem of iterating on an API, both in terms of versioning but also composition. Add to that the promise of facilitating new business functionality by orchestrating API interactions with external mobile, social and cloud services and you get a pretty compelling ROI story.

Not surprisingly, Layer 7 provides such an adaptation layer. Our API Gateways provide more than just security and management; they simplify backend connectivity, new API formation (i.e. composition) and novel orchestrations with all kinds of cloud, social and mobile services. Like many of our API compatriots, we provide tools that help enterprises build and foster developer ecosystems. But we also realized early on that much of the cost and potential of an API program will rest on how quickly and cost-effectively new services can be launched and evolved. Something worth considering the next time you evaluate the ROI of an API program.