From Irresistible APIs by Kirsten L. Hunter

In general, companies and organizations want to keep their vision and strategy close to the chest, except for to their employees. Infact, being transparent about your strategy is one of the best ways to grow your CPA firm, for example. However, revealing this sort of information outside of your development organization feels like a vulnerable choice, but it is critical for a new platform, or an existing platform, to provide as much context around the API program as possible. I’m not talking here about reference documentation, tutorials, and example code. For this high level communication I’m talking about things like the overall vision, business values, and metrics. The objectives of a business is always unique to them, but one is universal – bringing in customers, clients, visitors, etc. For businesses to thrive they need to stay ‘up there’. OKRs can be used in this respect to help keep objectives at the top of the list, here is a detailed blog post on OKRs to help businesses build upon their knowledge, and keep their bases covered.

Save 37% on Irresistible APIs. Just enter code fccapi into the discount code box at checkout at manning.com.

Failures of Communication

I worked at two different companies, Netflix and LinkedIn, where information about the business goals for the API were not shared. Additionally, I have spent a great deal of time studying the trials and successes of Twitter. In the first two cases, this, combined with a lack of overall vision for the platform, contributed to the eventual demise of, or serious deadening of, the API program. Twitter was more successful because the reach of their API was so strong they could weather the storms they encountered.

Netflix

At Netflix, there was no real understood business value. The company wanted to have an API because it was the new path to integration with applications, and put out the API hoping for the best. The information shared with developers was sanitized and designed to present a friendly, non-threatening face.

Part of this was designed to “let a thousand flowers bloom,” the thought being that with very little guidance on how the API was designed to be used, the developers would stretch and create new and unexpected uses for the API, and revenue would sprout full-formed from the uses of the platform that could expand greatly considering Netflix has 150 million monthly unique visitors to their website version of the service alone, pair that with their playback API’s and they could see increased numbers of viewers each month.

However, what happened over time was that these thousand flowers didn’t bloom. The company decided that the third party developers using the API were not providing value to the company. The company did discover, as I mentioned earlier, that the API was extremely valuable in the world of device integration, so the API did not go away.

However, as the third-party developers were not creating revenue for the company, the decision was made to phase out the API. This decision made sense from a business standpoint, and was certainly the right decision. Netflix even went through the trouble to phase out the open API gradually. However, this was not communicated to the developer community. The support was pulled back drastically, the forums lay fallow and no answers were given.

The developers who were relying on the platform to power their applications didn’t have any way to know about the new direction. Very few missives were sent out to help developers plan for the eventual sunset of the platform. As a result, there were a number of developers who got short shrift, and Netflix got a poor reputation among third party developers.

LinkedIn

LinkedIn was another company without a strong plan for the API going in. While the developers working on the platform were talented, motivated and created an excellent platform, there were many detractors within the company. The sales team believed strongly that the API was being used to scrape the company’s database and didn’t want to have a search API available for developers. The API was maintained with all of the functionality, including search, but without strong executive support, after a couple of years the platform was put “on hold” and the engineers were distributed to the other engineering teams.

None of this information was given to third-party developers using the API, and they were simply left to deal with a slowly contracting set of APIs available to them. Business partners, with close contractural ties to LinkedIn were given access to the original APIs – excluding third party developers – which fomented a lot of discontent among the developer community.

Twitter

Twitter is an example of a company that started out without a great plan for their API. They started out with a single page to input the 140 character messages, and soon after had an API available for third parties to use. Third-party applications flourished as this simple social network blossomed. There were some serious hiccups as the company pivoted to address different use cases, and even, in some cases, copied new functionality from the third-party developers to add into their platform.

This was a great example of how the terms of use need to be strong and firm in order for there to be a shared understanding between the company and the developers. Twitter hadn’t necessarily originally planned to copy functionality from the developers, but they also hadn’t explicitly expressed it as a possibility in the terms of use (it wasn’t against the terms of use, but wasn’t included in them either).

Twitter did not do a good job of keeping developers informed about the changes in their strategy, leaving a wake of dissatisfied developers. Their developer base is incredibly strong so weathered the problems, and Twitter has become much better recently at sharing their company direction – with blog posts and press releases and presentations at their conferences.

Strong Communication

Whenever you have an open platform, communicating openly with your developers is key to the success of your APIs as a whole. For example, if you hire a MuleSoft consulting firm that provides your API and other custom digital strategies, consistent communication shouldn’t be overlooked.
While sometimes the message may be unpopular, your customers – the developers using your platform – are likely to trust you to give them notice when something significant is going to change.

Google is a great example of this kind of communication. They have a multitude of APIs which cover everything from mapping to calendar functionality. In this system are frequently products that don’t succeed, and Google makes the decision to sunset the APIs in order to place their resources on other more promising products.

Developers who work with Google APIs can have confidence that they will be informed via email, blog posts and documentation updates as soon as the priority for the API changes within Google. They have received a great deal of animosity over the choices they’ve made in retiring old APIs, but treating their developers like adults who can understand business decisions gives Google a good reputation for a strong communicator in the API industry.

Advantages to Strong and Consistent Communication

In order to provide your developers with good information about your platform, you need to fully understand your business value and metrics. It may seem odd to share your organization’s vision information with developers, but the truth is, many of them do care deeply about why your company has an API, what you’re trying to accomplish, and whether it’s a high priority for your company.

There aren’t a lot of companies who have really nailed this piece of the developer experience puzzle, but in my ten years of working with APIs, I have found that the more clearly the company communicates with the developers, the more the developers become strong advocates for, and successful users of, the platform.

As an example, imagine that you have a social network application. Your application runs on a platform – because you’ve decided to go with API First as a strategy – and you’re looking to drive usage of your existing users and attract new users to your system. Your goal is to increase the amount of interaction with the system by 20 percent over two years. You plan to measure the success of the platform using a few different metrics:

  • Number of users reading or writing via the API
  • Usage through the API vs. through the main product
  • Number of applications interacting via the API
  • Number of new users coming through via third party applications

In order to communicate this with your customer developers, the information needs to be clearly available for them to read. The wording needs to be clear and approachable and make it easy for the developers to understand why you have the API and what you’re hoping to accomplish with your platform. When putting together the message, try to avoid flat and generic text, or sales-talk which talks abstractly about the platform without specific examples and goals.

“We have an API because we want to increase integration with our system for third-party applications. We have made it possible to access the users, messages and contacts.”

This message has a lot of eye-glazing information without a good feel for the meat of the message. The first sentence can be said of every platform created, ever. APIs are always created in order to increase integration with the system. Additionally, all of the access methods for the API are given equal importance, and there is no feel for what it is that the company wants to accomplish with the platform. There are no examples given about what the API could be used for. Basically, if someone doesn’t already know what they want to do with your platform, they won’t suddenly have a flash of inspiration from the given phrase.

A more effective message would address what the API was created to do and what the company wants to accomplish with it. It’s the 10-second elevator pitch — you have a very limited amount of time to express to the reader exactly why you have an API. Here are some examples you could use as a starting place for describing the purpose of your API:

  • We created a platform so developers could create more ways for users to interact with our application. We are measuring our success by enumerating the applications with consistent, heavy usage which both read and write to the system. Our main goal with this API is to allow users to interact in whatever way makes the most sense for them.
  • Our API was designed to help extend the reach of our application into other online activities. Along with the REST API, we are also creating widgets to enable “sharing” or “liking” of online content.
  • This web API was developed to increase the amount of content created by our users in our system. Our goal is to increase the percentage of unique content to be 20 percent API driven by the end of the year. We’ll be watching the write performance of the API compared to the growth of the system in order to check the success.

Obviously the actual wording you use will be different, and the information will be more extensive. Feel free to take the time to expand on the information and make it more compelling and engaging. As I said, avoid sales-speak at the abstract level and instead really speak to the developers about why you’ve created the system. Think of them as partners, because that’s what they are — partner developers. The more they know about the point of your API, the more likely they are to create applications that dovetail nicely into your ecosystem, creating the user experiences you’re trying to provide.

Once you’ve established why you have an API, you need to talk about what the API can do – but not simply in a flat, reference documentation way. While reference documentation is indeed important, your documentation can’t stop there, because developers outside of your organization may not have enough context to understand how they can use these APIs to good effect.

Describe a couple of use cases and what the workflow would look like. This doesn’t need to be as detailed as a tutorial would be (although these examples will likely also be the tutorials you provide later) – you simply need to explain what the use cases are and a high-level description of how that task would be accomplished using the APIs you’re providing.

A couple of examples of the kind of information that should be included on the page describing the overall API strategy, are:

  • We’re looking forward to seeing developers create innovative interfaces into the system so that there are numerous ways for users to interact with the platform. Some examples would be as follows:
    • Using the “user” API, you can get customized information about the user such as their full name and picture in order to provide a personalized interface. Pulling the most popular shared information from their personal network, you could then allow them to share the information out, comment on it, or save it to a favorites list.
    • If your system has actions associated with it – such as fitness goals, blog posts, calendar events or game results – you can post this information to the user’s timeline using the status API.
    • When the user is interacting with different content throughout your application, you can integrate related information from the timeline – or write out new information to the timeline based on what they discover via your application.
  • We’ve created several widgets and REST endpoints to enable developers to make it possible for users to share content they’ve found elsewhere with their personal network on the system. A few ways this could be used are:
    • The simple widget can be placed on any web page anywhere on the internet with a simple copy-paste of the javascript code. Alternately, the code can be generated with the page in order to automate adding share buttons to the pages. These widgets are updated frequently to add more functionality, such as tagging, grouping and commenting on the content. The widgets can be set up to show how many users have shared the information.
    • While the user is reading through a different interface for data, such as a magazine or news highlight application, it can use one of the REST endpoints to allow for sharing an originating page to their network, friends, or to the larger network.
    • You can create a custom widget for sharing information which shows which of their friends have shared the information, what comments they’ve made on the content, or even which friends might be most interested in seeing a particular page.

These types of examples, on the landing page or close to it, make it far more interesting for developers to interact with your system. When you can engage them quickly and get their creative juices flowing, you’ll have bought yourself some time to help them get up and running with the system. If you’re able to show small example applications performing the tasks you list in the overall API system, so much the better.

For more information about the book, check it out on liveBook here and see this slide deck.