Saul Caganoff, CTO of the tech and API business consultancy Sixtree in Australia (and co-organizer of the upcoming APIdays Australia focusing on platform innovation), says such issues are common in business, when a consumer of some supply service becomes too tightly dependent on the raw materials needed: "Typically the consuming system ends up too tightly coupled to the provider leading to disruption when the provider changes," Caganoff told ProgrammableWeb. "There are well established techniques to mitigate this coupling at the technical level, but coupling appears at all levels, from technical protocols and data formats through to business operations (such as changes in availability, or changes in pricing). You decouple by introducing abstractions, but they are expensive. The art is in getting the level of abstraction and decoupling just right. These considerations will become more important in the API world. If your business is too tightly coupled to a particular API, then you are carrying higher risk."
Key Issues for API Consumers in Managing Risk
Assess Risk Regularly
When Martin started RouteBuilder in 2006, the API landscape — and the mapping API space in particular — was quite different to how it looks now. Businesses using mapping products today can look at a range of alternatives to the Google Maps API, and may need to regularly revisit the available alternatives in their sector that could provide similar functionality. Such a regular review of available options is also recommended to ensure that the business is not only getting best in breed access to the API features they need, but also to help them identify if their are better priced options that have emerged more recently.
“I had not considered any other mapping frameworks prior to receiving an eviction notice from Google. My decision to migrate to OpenStreetMap was primarily driven by the open licensing terms. Had a truly free, viable alternative to Google Map exist in 2006 I probably would have used it from the beginning,” says Martin.
Caganoff says he works with business customers regularly on identifying what APIs they will be consuming and what risks these present in their business: "You need to understand the risks and the impacts of likely changes to your API providers. How critical is a specific provider to your business and what alternatives are there available if that provider goes out of business or sour's the relationship? If you are too dependent on someone else, then that is ultimately your risk, not the providers. Design your system and your business model so that choices can be made as late as possible and possibly even on the fly, when you are forced to change."
Risk solution: Create an inventory list of all the APIs your product or business process consumes. At least once a year, make a list of potential alternative APIs that provide similar functionality and calculate the alternative pricing models to ensure you are using the best value API for your business (other factors like stability, robustness and size of change required to change APIs may also factor into the pricing calculation). Review the terms of service of the API you are currently consuming and any alternatives, and start following the social accounts of API alternatives via blog subscription or social media to stay conversant with them in case the need to change arises.
Martin is still considering a move to OpenStreetMap following this recent experience, as the process of needing to find a solution helped him identify a possibly better fitting API for his product.
Risk solution: Once API alternatives have been identified, it may be worth doing a resource mapping and migration strategy outline to match resources and parameters from the API currently being consumed with the best possible alternative. Having such a migration plan ready would mean that an API consumer is more readily prepared to make the change if it becomes necessary in an urgent situation. And Martin has pointed out, with the 14 days notice he had been given, if that threat was real then he would have not been able to make the change in time, given his other life responsibilities. But for a business, 14 days should be enough time if there is a migration plan already in place.
Martin admits that for him, he wasn’t regularly keeping up with changes to the Google Maps API. “Usually changes would only come to my attention when a user notifies me that a feature has stopped working. That would be a terrible way to run a business, but it’s not a completely unreasonable way to run a free website,” says Martin.
Over the years, for example, RouteBuilder has had to upgrade compatibility to v2 of the API after backwards compatibility with v1 was unavailable, and in 2011 when Yahoo discontinued their geocode service, RouteBuilder swapped over to Google Maps’ geocode features which had not been available when the product was first built.
In both instances, RouteBuilder was only updated when users informed Martin of the broken features.
“More recently I’ve noticed that the Google Maps API team has taken to sending out emails when there are big API changes. I think that is helpful for developers like me who are not actively using it,” says Martin.
Risk solution: Always subscribe to any blogs or Twitter accounts attached to the APIs you consume. When new versions are released, make sure that your API is still compatible, and when new features or capabilities are made available, consider whether these could be incorporated into your product/process as new features. Reward users who alert you early when any API changes do impact on your product. Consider subscribing to a free service like API Changelog to track changes to the APIs you consume.
Key Issues for API Providers in Helping Consumers Reduce Risks
The Google Maps API team were quick to resolve the problem for RouteBuilder and wanted to strongly emphasis to ProgrammableWeb that the notice was sent in error and that RouteBuilder was never at risk.
Unfortunately, poorly communicated terms of service or erroneous communications can foster a sense of distrust and create disturbances within an API provider’s developer community. There are ways that an API provider can ensure strong developer community relations in the ways they manage and reduce risk for their consumers.
Emerging Best Practice? Flexible Terms of Service
Google’s API portfolio overall is noticing that in order to support developers to move at the same speed of innovation as the Alphabet company itself, the overall terms of service for Google’s products need to be more flexible. While the RouteBuilder communication error was in process, at the same time, Google was working with its larger developer community to provide greater access to their APIs.
“We adjusted the way we operate based specifically around the need for our consumers to pivot or add new features,” says Mara Harris from Global Communications and Public Affairs at Google Maps. “Our consumers need to be able to adjust quickly based on their business needs.”
Harris explains that now, companies can buy maps credits so that as they create products that use a range of Maps API products and services, their API usage can be increased or decreased as needed in the instant. “Now the way it works is that they can have access to multiple APIs, and innovate as quickly as we do. That change was made a week ago,” says Harris.
ABOVE: New credits based usage model and cost structure for Google Maps APIs (Source: https://developers.google.com/maps/premium/usage-limits?hl=en#maps-credits)
Harris says the change was made to help businesses meet their consumption needs. “It has been a combination of seeing what our customer needs have been. We come out with new APIs all the time and startups need to be able to react quickly and to move just as fast as we are,” says Harris.
Remove Complexity: Clarify Terms of Service Clauses
One of the frustrating issues that faced RouteBuilder in how the issue was explained to them was partly the language and referencing to the Terms of Service. For one, the initial letter from Google mentioned that the terms of service used a “wrapper”. However, the section of the Terms of Service — clause 10.4 (c) — referenced in the email did not user the term ‘wrapper’. Instead, it suggested that RouteBuilder was duplicating functionality that Google Maps itself offers, a valid reason for restricting API access.
Normally, 'wrapper' in API terms has come to mean a framework-specific code snippet that makes an API accessible in a particular language. Often, devs creating API wrappers in their preferred language or language framework is a sign of the network effect of an API’s growth, and should be considered a measure of success for an API provider, as it means that the developer community itself is evangelizing an API and making sure it is accessible to even more developers.
But whoever sent the email from the Google Maps team was actually referencing an out of date Terms of Service, says Martin:
I thought it was odd that the email I received introduced the term “wrapper”, when Google’s Terms of Service never uses that terminology. I dug up the November, 2014 copy of the Terms of Service where they did use the term “wrapping”, and it is solely in relation to wrapping APIs:
(a) No “Wrapping.” You must not create or offer a “wrapper” for the Service, unless you obtain Google’s written consent to do so. For example, you are not permitted to: (i) use or provide any part of the Service or Content (such as map imagery, geocoding, directions, places, or terrain data) in an API that you offer to others; or (ii) create a Maps API Implementation that reimplements or duplicates Google Maps. For clarity, you are not “wrapping” the Service if your Maps API Implementation provides substantial additional features or content beyond Google Maps/Google Earth, and those additional features or content constitute the primary defining characteristic of your Maps API Implementation.
They removed that section in the September, 2015 update to the Terms of Service, so to summarize: I was accidentally evicted based on the suspect interpretation of a clause from an obsolete Terms of Service.
Closing the Communication Circle: Connect Email Alerts to a Human Being
The experience of RouteBuilder and the research undertaken for this article suggest one final bit of advice for API providers is to find the right balance between operating at scale and encouraging self-serve, and providing real customer service.
One of the great trends in API adoption is to make it easy for developers around the globe to sign up for an API and immediately starting playing with it. This self-serve nature of APIs has been crucial in helping API providers build strong developer communities and ramp up adoption. Industry thought leader on API adoption, Carlo Longino, says this is one of the seven steps to successful developer onboarding in his API University series, How To Build a Strong Developer Community.
So having an automated workflow that triggers welcome emails and engages with developers at any time of the day or night makes some sense.
But if an issue escalates, or if someone queries the content of an email, then it is best routed to a user success manager or customer support worker. After issuing the cease-and-desist email from Google Maps, Martin had no way to follow up and alert the team that his use wasn’t in contravention of the terms of service. This lack of a listening channel for the developer-consumer quickly creates unnecessary angst and worry.
When trying to track down a Google Maps API representative for this article, I emailed the API sales team at Google Maps, explaining I was a writer for ProgrammableWeb and explaining my request. I also reached out via their Twitter account. Twitter didn’t respond and instead I received a series of emails from the sales team that completely ignored my request and instead kept asking me about how many map customers I thought I would have and to describe the application use case. Perhaps it was Google’s AI RankBrain that was actually trying to speak with me, and my request fell outside its parameters of a potential query-and-response automated workflow. Luckily, my editor at ProgrammableWeb was able to give me some internal leads who responded within 15 minutes. But developer consumers like Martin don’t have access to those networks, and instead can feel increasingly marginalized by an email response that either ignores them or sends back automated, incorrect information.
Risk Management: An Essential Part of the API Consumption Lifecycle
As open APIs get baked in to more products and business processes, it will be essential for businesses to treat APIs the same as any other supply good and to flag API consumption issues in risk management strategies. Businesses that require third-party APIs in their products, services and workflows need to identify alternatives, regularly review their access rights, and be prepared for mission critical changes.
For API providers looking to maintain and build trust with their developer community, how changes are communicated and how access to an API is maintained can be a quality component in communications and customer management.