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.

How does Layer 7 help me manage a range of devices across IoT?
IoT is an opportunity for CA and Layer 7 to bring together identity, access and API Management.  To paraphrase a comment on a recent Gigaom article: Everything with an identity will have an API and everything with an API will have an identity.

With so many “things” potentially accessing APIs, what are some strategies for securing these APIs across such a breadth of consumers?
Identify, authenticate and authorize using standards. API for IoT means managing identity for many devices at Internet scale.

How will API discoverability work with the vast number of things, especially if we see REST as the primary communication style?
I reached out to my colleague Ronnie Mitra for this answer. Ronnie pointed out that, in the past, standards like UDDI and WSRR promised to provide service registries but that didn’t really work out. Nowadays, we see lots of independent human-oriented API registries and marketplaces that might have more chance of surviving. There are even some runtime discovery solutions like Google’s discovery interface for APIs and the use of HTTP OPTION to learn about APIs. At the moment, lots of people are trying lots of things, unsure of where it will all end up. It would be interesting to dive deeper into why we need discoverability to power IoT and when that discoverability has to take place.

How can API security get easier when API demand grows exponentially? There’s a big disconnect.
It doesn’t get easier. Transport-level security is reasonably well understood but endpoint identity and trust will be challenging.

Where will the intelligence be in IoT? Will there be some form of on-site intelligence, so that core functionality continues even if the connection is lost? Or will all intelligence be cloud-based?
It depends on whether you design for centralized “hub and spoke” or decentralized “domains of concern”. The former is responsible for correlating data and events within the domain whereas the latter is responsible for communicating with other domains (I owe this concept to Michael Holdmann’s blog). “Domains of concern” design communicates with different domains for different purposes –  in an apartment for home automation, in an apartment building for HVAC, in a city block for energy generation/consumption, in a city for utility grid etc. Emergencies or out-of-bound signals are handled like exceptions and are bubbling up through the domains until intercepted. But most things will serve an inherent purpose and that purpose will not be affected by the absence of any connectivity. There will be intelligence within the core of each domain as well as at the edges/intersections with other domains.

What is the best way to overcome fear of exposing data via APIs in an enterprise?
You need to identify a business opportunity. Unless you know what business impact you are trying to archive and how you will measure it, you should not do it.

Does IoT require a strong network or big data or both?
Not a strong network but ubiquitous connectivity. Not big data but sharing/correlating data horizontally between distinct vertical silos.

What significance (benefits/drawbacks) do the various REST levels have with respect to the Internet of Things (connecting, monetizing etc.)?
I had never heard of levels of REST and had to look it up. Turns out the levels are: resources, verbs and hypermedia. Hypermedia would allow you to embed long-lived clients, which could adapt to changes in API design. But it is actually the data or service behind the API which is monetizable, not the API itself. The API is just the means to an end.

How will IoT evolve? And more importantly how can enterprises solve the security and privacy issues that will arise as IoT evolves?
Culturally, the European regulators will try to put privacy regulations in place sooner rather than later whereas the North Amercian market will initially remain largely unregulated until some abuse prompts the regulator to step in. In Germany, the federal regulator tries to stay ahead of the market and recently published a security profile for smart meters. Personally I would look at designing M2M and IoT applications assuming that endpoint data is inherently unreliable and that I can not necessarily trust the source. But that is very broad guidance and may or may not be applicable to a specific use case.

As we create API frameworks that interact with sensors and control objects in the IoT what/who are the best organizations to follow to learn about new protocols that we should be preparing to handle, such as CoAP etc?
Here are some suggestions:

• IPSO Alliance
• ETSI M2M
• ITU M2M
• oneM2M
• Eclipse M2M

How close are we to having a unified platform for IoT application developers and who is likely to be the winner among the competing platforms?
Chances are there won’t be a winner at all. You have companies like Axeda, Exosite, Gemalto, Digi, Paraimpu, BugLabs, ThingWorx, SensiNode, deviceWISE and more. You have industry working groups like Eclipse M2M and various research efforts like SPITFIRE project, Fraunhofer FOKUS, DFuse and many others. The Eclipse M2M framework is probably a good choice to start with.

Even assuming ubiquitous and common networking (e.g. IPv6 on the public Internet) – how will the IoT identify peers, hierarchy and relationships?  
I think there is a huge opportunity for identity companies like CA to figure this out. Take a look at EVRYTHNG as one of the few startups in that space. Meanwhile, the folks over at Paraimpu are trying to tackle this challenge by combining aspects of a social network with IoT.

Since our founding, we have preached the vision that enterprises can open their data and application assets programmatically in a secure way. When we started off, the primary driver for opening up was tighter business integration with partners. Today however, the demand for opening up data and application assets has exploded alongside the growth of mobile, cloud, Big Data and the Internet of Things (IoT).

The idea of organizations as walled-off castles is gone. Mobile is forcing organizations to deliver new business apps to customers and employees beyond the enterprise perimeter. Cloud is redefining how applications are consumed and delivered across a hybridized, extended organization. IoT will upend our notions of outside connectivity and data processing. APIs play a central role in making all this happen. Layer 7 gives customers the confidence to open up via APIs, without compromising security or operational integrity.

For us at Layer 7, security has always been a paramount consideration because our customers are enterprises and enterprises care about security. The CA Technologies acquisition reflects a common point of view on how to deliver new business value in mobility, cloud etc. while protecting the data and applications that are the lifeblood of a today’s enterprise.

CA and Layer 7 both appreciate that the old enterprise security perimeter is disappearing and that the only way to effectively enable online business while protecting information assets is to make identity the new perimeter. We need to focus on managing who gets access to what and what they can do with data once they have that access. Put another way, we need to focus on the identity, data and access that drives modern initiatives around Web, mobile, cloud, social and IoT. Together CA Technologies and Layer 7 Technologies offer enterprises the first truly multi-channel approach to enabling the business while securing its information assets.

Looking into the future, one clearly sees the scope for APIs will increase. IoT will make every formerly detached device connected – all through APIs. Where networking used to be about discrete routers and switches, it is now being transformed, via SDN, into something that is programmable and agile – again, this will be brought to you by APIs. And as for the server and storage infrastructure that underpins the data that drives the Web and mobile, Amazon Web Services has given us a glimpse of the future. As the “Web Services” part of that name suggests, APIs will play a significant role in provisioning in management of the cloud.

As we join CA Technologies, we now have the necessary reach and breadth to make Layer 7 the unassailable leader in the API security and management space. For customers, this means more of what they liked plus the ability to accelerate delivery of our original vision. We’re here to help organizations open up via APIs. And we’re open for business.

We know that connectivity and message-based integration are not new concepts for the financial industry. Enterprise architects in the banking world are masters in the art of connecting old systems with new facades and exposing backend resources through multiple channels. But up until now, a conversation with these professionals would be dominated by concerns rooted in the Services Oriented Architecture world: “How do we prevent service proliferation?”, “How do we secure SOAP conversations?”  In fact, it wasn’t too long ago that the mere mention of an API as a strategic initiative would leave these enterprise architects scratching their heads.

Fast forward to today and many banking technologists are explicitly asking for API Management solutions.  They know the terminology of the space, they know what they want to achieve and they know the pitfalls they wish to avoid. In addition, I’ve been amazed at the depth of knowledge that has emerged among these teams, as enterprise developers have invested their own time to learn from relevant tutorials , articles and – of course – blogs posts. The caricature of the enterprise developer as a SOA dinosaur struggling to understand the “new stuff” is fast becoming a myth.

To be fair, there is still great hesitation within the industry when it comes to opening up data and losing control of the user experience but that isn’t stopping banks from applying good API design practice internally. As we’ve said before, APIs are not simply about reaching  anonymous third-party developers. Indeed, organizations can gain great benefits by applying API Management to the interactions that take place in private for their own apps and partners.  But I’ve been astounded by the handful of architects in the banking world I’ve met who are actively experimenting with public API releases.  It seems that the fear of losing control over data, services and products is beginning to lose out to the perceived value of growing the business through a new channel.

Banks provide a great indicator for the direction of enterprise technology and it certainly seems that the “API thing” has legs within this space. If you are in the enterprise world, make sure you have considered how launching an API program might help your business – because it’s increasingly likely your competitors are already doing so.

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.

“Government information shall be managed as an asset throughout its life cycle to promote interoperability and openness, and, wherever possible and legally permissible, to ensure that data are released to the public in ways that make the data easy to find, accessible, and usable” (emphasis mine).

No Dumping
The usual approach to this type of work is to simply publish raw data in a directory or repository and then create some fencing around the data that helps track usage and distribution. Essentially, making government data “open” becomes a data dumping operation. This practice fails on all of President Obama’s three key points. First, data dumps make finding valuable information not at all easy. Second, even though the content might appear in a standard format like XML, CSV or JSON, it is hardly accessible (except for to geeks, who love this kind of stuff). And finally, raw data is hardly ever usable. Instead, it’s a mind-numbing pile of characters and quote marks that must be massaged and re-interpreted before it comes close to usability.

So, while this new directive offers an opportunity to make available a vast amount of the data the government collects on our behalf, the devil is in the details. And the details are in the interface – the API. As with poorly-designed kitchen appliances and cryptic entertainment center remote controls, when it takes extensive documentation to explain how to use something, the design has failed. There’s a simple principle here. Poor API design results in unusable data.

Affordable Data
It doesn’t have to be this way, of course. Government departments have the opportunity to implement designs that meet the goals set forth in the executive order. They can make it easy for people to find, access and use the data. They can publish not just data but APIs that afford searching, filtering and exploring the data in a meaningful and helpful manner; APIs that empower both users and developers to successfully interact with the data, without resorting to a dashboard featuring dozens of options or mind-numbing explanations.

In the (likely) event that the initial open data release consists of mere data, companies and individuals would be well advised to resist the temptation to build a multitude of “one-off” applications, each of which solves a single problem or answers a narrow set of questions for some subset of the data. Instead, work should be put into converting the raw data into usable API formats such as Atom, OData, HAL, Collection+JSON and HTML (to name just a few). APIs should be designed with the same care that would be given to any interactive experience.  Investment in tools and technologies that can properly represent the data in multiple formats while supporting various use cases and access requirements will yield great results.

Open Data APIs
In the end, organizations that know the importance of a good interface, the power of choice and the freedom of flexible representations will be able to convert raw data into valuable information, which can be consumed by a wide range of users, platforms and devices. These considerations are essential to building and supporting open data APIs.

Because – ultimately – data isn’t open, unless it’s “easy to find, accessible, and usable”.

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.

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.

We’ll also talk about the “-ilities” of an API Management platform: scalability, manageability, extensibility etc. We will illustrate each of these with a real-world Layer 7 customer example. You’ll see why these and other non-functional requirements matter just as much as the solution’s technical capabilities.

So, please join me and Layer 7 Product Manager Dana Crane as we discuss these key API Management criteria tomorrow. There will be time for questions – both technical and conceptual – and all attendees will receive a free copy of the recently-published Forrester Wave for API Management Platforms. See you tomorrow!

Register now for How to Choose the Right API Management Solution >>

Mobile devices and social media have multiplied the number of touch-points available for engaging buyers. The line between retail and “eTail” has grown blurry as location increasingly defines all shopping experiences. Big Data now makes it possible for marketers to tailor promotions to every shopper, based on buying history and inferred intent. And API-driven architectures provide a way to tie all online channels, data sources and cloud services together in an event-driven, context-aware network that can engage buyers wherever they are.

All these elements assembled together suggest a new era of personalized commerce. This will place the buyer back at the center of a commerce universe of disparate data, mobile, cloud and social elements that will converge to deliver him or her a more exact shopping experience tailored to his or her choice preferences at that point in time and that place in space.

For Layer 7, this convergence of trends that puts the shopper at the center of an API-connected ecosystem plays to two particular strengths. Firstly, it leverages Layer 7′s leadership in networking enterprise, mobile, social, cloud and partner services via APIs. Secondly, it cements a concept of enhanced identity, where a fuller user profile can be built around an ID to deliver a more complete view of that subject. Both will be essential for delivering on the vision of highly-personal commerce that spans online channels, is location-aware, leverages multiple data sources and can determine a context-specific action across mobile, payment and Web services.

To learn more, read the API-Driven Omni-Channel Commerce solution brief >>