Ronnie Mitra

Ronnie Mitra

Ronnie Mitra is an expert in enterprise development and integration who leads Layer 7’s API Architecture & Design Practice across Europe. In this role, Ronnie helps companies leverage their burgeoning API potential. Before joining Layer 7, he worked at IBM where he held the worldwide leadership role for WebSphere connectivity products.

August 30th, 2013

Kobo Says Goodbye to the Goodreads API

Written by
 

Kodo/GoodreadsAn API-related news item that caught my interest earlier today speaks volumes about the nature of the burgeoning API market. Kobo  (a seller of eBook readers), has decided to stop using the open book recommendation and review API provided by Goodreads. The reason?  The social site for avid readers was acquired a few months ago by Amazon, which just happens to lead the eBook reader market with its Kindle product.

Acquisitions impacting business partnerships isn’t a new concept. But this event is significant because it highlights a few truths in the Web API space…

APIs Can Change Hands
At one time, Kobo was using a public API offered by a company that had developed a review and recommendation engine that was a serious competitor to Amazon’s.  But – post-acquisition – Kobo found itself in the awkward position of doing business with its main competitor. Not a deal-breaker in itself but it shifted the relationship enough that Kobo had to walk away.

APIs Need to be Mutually Beneficial
Doing business with a competitor is a normal part of most large operations and when your competitor casts as massive a shadow as Amazon does, it becomes almost unavoidable. But public API consumers like Kobo can find themselves in the unenviable position of not having any leverage when consuming a free API. To support a long-lasting business relationship, it is important that both sides benefit from the contract. Kobo’s benefit was obvious – offering readers a high-quality recommendation and review interface translated to a richer user experience and increased sales potential.

So, what did Goodreads get out of the arrangement? From the site’s public terms of service, it appears that marketability and branding were big drivers, as API consumers must display Goodreads branding and links to comply. Kobo may have made a special commercial arrangement with the Goodreads site in order to use its API commercially but it is unlikely to have been one that would have benefited Amazon enough to make it worth supporting a competitor. Once Amazon purchased the Goodreads company and its data, the balance of benefit shifted towards Kobo.

API Providers Can Lose Customers
What I find most fascinating about this story is the fact that Kobo stopped using the Goodreads API before Amazon forced it to. As far as I can tell, the terms haven’t changed significantly, the data is still available and Amazon has stated that it plans to keep the API open for Kobo. Despite all this, Kobo made a decision to walk away. Perhaps taking a hit on features now made more sense than being at the mercy of one of its biggest competitors. For API providers, it is a reminder that your consumers aren’t forced to continue using your APIs. In the future, providers may find that keeping consumers happy becomes just as important as finding them in the first place.

API Consumers Need to Consider the Worst
After Amazon acquired Goodreads, some apprehensive users sought out
alternative sites. While some of these reading sites offer APIs, it appears Kobo has decided to harvest data on its own, having recently announced its entrance into the social reading arena. Putting aside the chances of success, this strategic move highlights the need for businesses to plan for data and service disruption. It means considering the potential impact of having the API you’ve built a business on disappear, even if temporarily. As any lawyer will tell you, planning for divorce before you get married is just common sense.

This decision may be a turning point for one of the companies in this story but that isn’t why I found it interesting. Instead, it is a stark reminder that market forces can have a great impact on the APIs we are learning to rely upon. We often focus on the technical and design aspects of Web APIs but we mustn’t forget that they exist within a dynamic market and both providers and consumers need to be vigilant about handling change.

June 19th, 2013

When Good API Design is a Waste of Time

The idea that good design is essential to building great products and services has become a truism in our industry.  Most of us intuitively understand the idea that expending effort on the design of our code, system architecture and APIs will payoff after implementation.  I’m certainly a big believer in the power of good design for the API space, but I wanted to explore a situation where a design focus might not be necessary.

Consider the case of a small business offering a cloud-based service product for a niche market.  If this business chose to invest in a well-designed, developer-centric API, at a minimum they could expect:

  • A reduced learning curve for developers consuming the interface
  • A reduction in troubleshooting time
  • Increased interest from their developer community

For most audiences, these are goals worth achieving.  Indeed, this is why we emphasize good design for APIs in the first place – the benefits fit remarkably well with the main reasons for embarking on an API strategy: reduced cost and increased adoption.

But, in my conversations with connectivity professionals from larger organizations, it is apparent that not all service vendors see the value in investing in this type of design effort.  Developers and architects are bursting with  tales of forced integration with service providers who have simply thrown an ugly or barely functioning interface on top of  core component.  It is in these scenarios that we hear about laughable attempts at implement whichever API styles and features are in fashion.  ’REST’ and ‘security’ become sales-worthy buzzwords that don’t live up to their promise when developers get their hands on the actual interface when real project work commences.

In the majority of these cases, technical teams have very little say during the procurement process of outsourced and cloud-based services.  In effect, these API providers don’t need to design for their developer audience because they aren’t critical to succeeding.  For many years a sound strategy for selling cloud-based products has been to sidestep technical teams and engage directly with the business.  It’s frustrating that technology teams are often still left with the responsibility for reducing integration costs regardless of the lack of sophistication in the APIs that they are tasked with connecting to.

Thankfully, the wealth of knowledge and connectivity products in the enterprise space allows these teams to reduce the impact of bad design on the overall project and organization.  Components such as API proxies can be used not only to build a facade for APIs that are being exposed, but also to provide abstraction for services that are being consumed.  In essence, the design burden can shift from the service provider, to the enterprise developer who wraps a poorly designed interface in a more consumable, developer-friendly API for the rest of the organization to use.

As a whole, the scenario makes sense.  Well designed products are based in part a designer’s empathy for their users.  Good design involves perceiving a product from a user’s view point along with an understanding of the impact that design decisions will have on the user base.  However, an organization that builds an API as an afterthought for developers, who are only viewed as a means to an end, will likely produce a poor API.

Ultimately, building a technology business based on developer apathy is a bad idea.  The industry shift towards API product based integration is empowering technology teams at all levels and services that continue to ignore the needs of their developers will eventually be ousted from the market.  In short, good design is only a waste of time when you don’t care about your users.  If  in fact you do care about the developers who will be using your API product, then you need to invest in designing your API with their point of view in mind.

June 10th, 2013

The WADL is Not Enough – Why API Documentation Matters

The WADL is Not EnoughAs 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.

May 31st, 2013

Banking on APIs

Banking APIsSomething has changed in the world of banking technology. Over the last few months, the architects who shape IT strategy for banks have started talking about API programs with an enthusiasm and energy that was barely at surface level in 2012. I can’t put my finger on exactly what has changed but IT leaders in the financial services world are moving towards implementing API strategies as a legitimate method for supporting a wide array of business drivers.

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.

January 25th, 2013

Considerations for Private APIs

Written by
 

Considerations for Private APIsIn the past, we’ve talked about the nature of private APIs (those interfaces that are built primarily to serve an organization’s own projects rather than to fulfill the needs of others).  But what are the specific challenges and architectural decisions that need to be made when implementing a private API?

First and foremost, an API can’t be considered private if it is open for widespread public use, right?  A simple way of keeping an API private is to host the interface on a public network without explicitly advertising or documenting its existence.  This can work well initially but may lead to problems in the future. If your service is valuable enough that others want to get their hands on it, even an undocumented, unsupported, private API can easily end up becoming a depended-upon API for application developers, resulting in an outcry when the API publisher has the audacity to modify or retire its own service.

A better approach is to provide access control at run-time and restrict usage of your API to a few known parties. There are a great number of methods for protecting access to internal resources but the best ones are those that achieve a balance between ease of implementation and resistance to infiltration. Security at all costs can greatly increase the complexity of an interface and – in turn – the time required to complete the projects that depend on it. Instead, we need to implement access control that is practical. Thankfully, security protocols like SSL, HTTP Basic authentication and OAuth 2 are great for providing the basic level of access control needed to make it difficult for outsiders to use a private API. Bear in mind that there is much more to API security than simply validating identity but this is the minimum level needed to ensure a degree of privacy.

Although a private API’s developers are generally known to the publisher, the best private APIs utilize API portal components to provide self-service registrations and integration to their private developer communities. This can greatly reduce the friction involved in getting API integration-based projects started and reduce the overall project costs for B2B and mobile-based initiatives. In fact, many of the lessons of simplified design, documentation and administration learned from the public API world can be directly applied to private API management. While the ultimate goal may be different (driving efficient API usage for private APIs rather than far-reaching adoption of open APIs), the ways of getting there are largely the same.

A unique characteristic of private APIs is the need to manage groups of developers. Unlike the public API space, private API publishers will often define out of band contract terms before offering up a quick self-service integration mechanism for that team. This type of group-based role definition is particularly common in integration projects that occur between organizations and can stretch the limits of API portal software that has been built primarily for open API use. Ideally, an API portal should at least be capable of managing developers within groups, communities or organizational affiliations as part of the self-service registration process. Even better, the portal could  provide capabilities for managing whole communities as separate domains within the same infrastructure.

Designing a private API certainly requires a different perspective but the good news is that much of the knowledge around public API design can be directly applied to interfaces you want to keep secret. Of course, building the management and security capabilities required to expose the API to your trusted parties can be daunting but that is why a great API management portal and gateway combination can save the day.