Chapter 6. Defining the value for your API

This chapter covers

• Business goals
• Metrics
• Use cases

Designing an API should always start with the process of determining business value and how you’ll measure it, followed by determining use cases to make sure you can build your design and strategy with confidence. Doing this for a web API brings it into line with other company products and helps you to both communicate your goals and success to your executive team and make sure your API is staying on track to success. Having these goals and metrics in place will also help you verify that the API is moving in the right direction, so you can determine whether you need to “pivot” your goals, metrics, or use cases to more directly match how client developers are using the API product.

6.1. Business goals

Understanding and communicating the API’s business value to your company, including goals to measure success, is critical. This is the information you’re going to communicate to the executives and other teams at your company, helping them understand why you have an API for your company. A product that can’t demonstrate success to the executive team is at serious risk of losing the resources needed to drive it. The ability to track and communicate the goals and strategy for the API and how it will contribute to the company’s bottom line will keep your product on track. A solid grasp of the business value will additionally help guide your design and development and make sure you end up with an API that meets the need you’re trying to address. Without a clear vision for the API, you’ll end up with a process that feels like herding cats, where you try to create a cohesive strategy on the fly. Take the time to figure out exactly what you want to get out of the API before you start working on the next steps. The easiest way to do this is to determine what your company is striving to accomplish in general and decide what web API business value would best support these goals.

Common goals for successful APIs vary widely. This chapter discusses several existing models, but asking, “What’s the API going to add to my company’s success?” will help guide you to the correct type of goal for your product. The values I discuss in this chapter cover monetization, usage, partner retention, and market dominance.

6.1.1. Monetization

Monetization is the most common business value that people attempt to accomplish. When the API is the main or only product for the company, this is an obvious necessity. In other cases, this is not an appropriate goal for the API. The reason is that it’s quite challenging to drive usage of your API when it is competing with the goals of the main product. When an API is supporting the main product, it’s important to make sure that the goals for the API are complementary to that product. In that case, your API will suffer from a lack of uptake if developers need to contend with money issues with the API. Ensure that the API encourages those client developers to create applications that strengthen the core value of your company’s main product or add new ways for users to interact with the system. When your API is not your main income stream, find ways to add to the company’s success without adding friction to the adoption of your API with a monetary cost.

Twilio is a company where the API is its main product, and a great example of a company where monetization is the main goal of the platform. It’s made difficult telephony interactions simple for developers, and in return its customers (client developers) pay Twilio for usage. The whole company is designed to support the web API platform, and it’s been successful as a result.

Marketing at Twilio is based on driving usage to the API. An army of developer evangelists works in the marketing organization and is constantly attending hackathons, helping developers integrate phone or SMS services into their applications. By providing the ability to integrate easily with telephony services, yielding a huge value for many application users, developers are motivated to pay money for the services they receive from Twilio.

Monetization for Twilio is directly tied to the developer usage of their API. Each call to the API costs a small amount, so an application using Twilio as part of its stack will provide Twilio with income relative to the success of the application. In this way, Twilio gets a small part of the income generated by each developer for a part of the functionality of the developer’s application itself.

Its developer portal is one of the best in the industry (see figure 6.1), because developers are their direct customers, and in order to thrive they must support those customers well.

Figure 6.1. Twilio has a strong developer portal. All portals should have API documentation as a quick link, but many other items are required to make a great portal. Articles about the system can help developers understand the underlying technology, such as the Security section here. Most important, the Getting Started section includes guides and libraries to help developers get going quickly, keeping the Twilio five-minutes-to-first-call goal in mind.

Twilio has a strong focus on making the developer experience easy, striving to make sure that a developer who visits its site can make a successful call to the API within five minutes—an aggressive goal that helps ensure that developers don’t get frustrated and give up on the API quickly. Twilio is also quite determined to retain its place as the dominant player in the SMS API industry. When your business case is tied so closely to revenue for the company, it’s not that difficult to generate support from the executive team. But don’t despair if this isn’t your business value—I talk through various other models throughout the chapter.

Twilio’s model for its API is currently represented by figure 6.2. As time goes forward, it’s added new features into the system. But the interaction for the client developers remains the same. That makes the platform increasingly valuable for those application creators.

Figure 6.2. Twilio’s API interacts with services in the messaging, voice, and video space. Each of these functions works directly with the same API, making it easy for developers to integrate multiple segments into applications. The API is like a central routing station, moving requests from the client developer’s application into the correct part of the Twilio API portal.

In figure 6.2, it becomes clear that Twilio has set up the system to be a single interface to each of the telephony systems. In this way, developers never need to interact directly with the systems themselves and can leave all that heavy lifting to Twilio. Because the functionality provided is time-consuming to implement for a single application, Twilio’s offering is generally considered by developers to be well worth the cost.

Monetization, then, is a valid business goal. In this case, it’s not hard to explain to your executives or other teams why you have an API. But if your API is an enhancement to your main product, it’s easy to fall into the trap of expecting your API to directly generate revenue. Without a strong business case around the API, you’re not likely to generate enough revenue to justify the resources needed to create and maintain the API—and these are the APIs most likely to be deprecated in favor of other, more profitable products. When your API is an add-on product, strongly consider one of the other business value choices, and see if one of them is more appropriate to your overall business strategy.

6.1.2. Usage

Sometimes the goal of the API is to drive usage, or how many times the end user interacts with your system. These users probably won’t spend all their time in your application, but if you have a product with an activity feed or other stream of information—if you have any type of social-based application—encouraging users to write to your system will drive interest and increase platform functionality for all your users, including the ones who don’t actively share information within your system. Providing a means for other applications to write activity into this stream will increase the perceived value of your system for your end users. Most social systems rely on advertisements to generate revenue, so the more compelling and engaging the activity stream is, the more eyes they’ll be able to sell to advertisers, and the more money they’ll bring in.

Twitter, LinkedIn, and Facebook are excellent examples of this type of product. Each of these systems relies heavily on content generated by users in order to create interest and engagement. Making it easy for a user to share interesting content with their network—and extended network—encourages people to contribute meaningful content to your ecosystem. If users are reading articles they enjoy on a news site or blog, it should be simple for them to share that information with everyone in their network and add that content to the ecosystem for your product. Figure 6.3 shows a blog post from my blog with sharing buttons for major networks, allowing people to share my page among their social networks.

Figure 6.3. Blog using a widget that creates and drives sharing icons for the main social platforms. Because each platform has a well-understood, well-described, and consistent API, developers can easily create integrations into these social platforms, and blog owners can plug in widgets with this functionality in a few minutes.

As you have probably noticed, these sharing icons are everywhere throughout the web. Social systems want to drive the addition of fresh content into their platform to add value for their users, and content owners want to encourage people to read the information they’ve posted. The use of these buttons drives new and relevant information to users’ information streams, increasing the value of a social platform. This interaction is generally a widget that uses the web API to provide the functionality. In this case, the ability to add the ability to share content back to Twitter (or other social systems) is extended to content owners, such as bloggers (as demonstrated earlier) and news websites. When you’re designing an API for usage in this way, it’s important to make it easy for end users to add content into your system to keep it lively and engaging.

Twitter makes money largely from advertising and selling data about the information in their system. In order for the advertising to be compelling to users, Twitter can use the activity stream to better understand each customer’s interests. Additionally, constant generation of new content ensures that the data remains germane to the partners who consume it. Its APIs are focused on engaging new users and keeping its existing users active and involved in the ecosystem.

LinkedIn had a complicated API, but it has since been throttled back, largely due to the determination of business value and the excessive cost of providing the majority of its APIs to third-party developers as well as partners. LinkedIn’s success is largely driven by revenue from advertising and recruiting. This revenue is increased by the number of users in the system and how often they interact with the system. LinkedIn wanted to bring new users into the system, engage existing users as frequently as possible, and make it easy for recruiters to find qualified candidates. Because of this they’ve recently focused on a few API-related offerings for developers and content providers. For instance, allowing developers to enable their users to sign in with LinkedIn gives them the opportunity to manage the user identity for those applications, staying at the front of the users’ minds. The sharing widgets, built on a back-end web API, provide content providers with the ability to allow readers to share interesting content within the LinkedIn ecosystem.

Facebook continues to offer several different API products (see figure 6.4). It has always wanted to drive usage of applications to its system, encourage the development of third-party games and applications that use the Facebook system, and generally drive up the percentage of time users spend connected to its system.

Figure 6.4. Facebook’s multitude of API offerings show the vast number of integration points it has created into its system. The most basic social platform integration—sharing widgets—is quite easy to use, but the Facebook platform includes complex integrations into the social graph (how people are related), monetization for games, and a game platform that provides much of the needed functionality for creating Facebook games.

Facebook has an SDK system for developers to use to integrate their games or other applications into the system, encouraging users to interact with Facebook more frequently as they play with these applications. Facebook additionally provides an API to add monetization to games, allowing users to purchase items for use within the game by interacting with Facebook directly. The combination of these two interfaces has helped Facebook become the most successful game platform among the social networks.

The Facebook graph web API allows application developers to integrate Facebook’s social data, including friend and demographic information, into their applications once the user has approved this access for the application. Any time you’re asked to check with Facebook and give permission for an application to access your own data, this developer is using the Facebook graph API to bring your information into an external website or application.

In short, usage is a strong driving force for social media. These three companies aren’t the only ones that derive value from a strong, relevant stream of new information. Any company wanting to increase the amount of information created for its system can consider whether this type of business value makes sense for its platform. Note that in many cases this functionality is extended via a plug-in or widget, but these features are driven by web APIs and are consistent with the general purposes of other REST-style APIs, even though they’re wrapped in handy packages for website creators to use. In these cases, the widgets and plug-ins are the customers of the API itself, but their existence is reliant on the existence of a strong, healthy platform.

6.1.3. Partner retention

One of the strongest business values for an API is partner retention. When your company has a solid relationship with another company, it helps create a strong revenue stream on which to build your other income. Losing these partnerships can create unstable revenue streams, causing problems for your company. To help avoid this problem, create an API that focuses on usability targeted at the use cases your partners may want. This could include automation within your system or integration of your reporting with their own dashboards. Partners who have already spent the time to integrate your systems into their own products or applications are less likely to move to a competitor, particularly if your API is in fact a first-class product and you keep new features in parity with your main product.

FedEx

FedEx is in a highly competitive market, but it was the first to create a strong API system for logistics, shipping, and tracking. It has enabled many small companies to become competitive by reducing the need to create extensive infrastructure to market and deliver their product.

For example, the flower delivery company FTD has historically been a major dominating force in flower delivery. It provided nationwide flower delivery to customers by partnering with local small delivery shops, which could bring flowers to people in their area. This allowed them to hold a virtual monopoly in the industry, as local flower shops didn’t have any way to attract customers in their area as easily as FTD could, and had no way to deliver flowers in other areas without arranging for shipping manually (see figure 6.5).

Figure 6.5. Before the FedEx platform became readily available, FTD enjoyed a virtual monopoly in the flower-sending industry for nonlocal deliveries. It worked with local florists (and was able to impose strict guidelines and pricing) and made it easy for consumers to send flowers anywhere in the country. But the system wasn’t set up so that the best florists were successful; FTD made it so that partnering with FTD was an important business decision for florists.

By integrating with FedEx, though, smaller companies have been able to enter this previously closed market (see figure 6.6). Customers of these client developers have a better way to track their packages without reaching out to either the application owner or FedEx, and the partners can focus on the core business case without becoming experts in the shipping industry. Once this integration is done, it’s a lot of work for a company to switch entirely to a competitor, which cements FedEx’s place in the industry. In this way, FedEx has created a situation where it’s likely to retain partners who are integrated deeply with their reliable API and who have improved their own processes as a result. It would be quite difficult for another shipping company to entice one of their partners to switch to its service, because that would require proving that the new service was good enough to cause a shift in experience for their customers and a significant amount of development time to change the integration.

Figure 6.6. Once FedEx provided a platform for local florists to use, it was no longer necessary to partner with a large company such as FTD in order to receive and process floral deliveries remotely. Now that there are ways for local companies to deliver their specific products with a minimum of effort, the competition is focused around the value of the products and not partnerships with specific companies.

6.1.4. Market dominance

Market dominance is different from partner integration in that the goal is for the company with the API to become the leader in its industry, rather than enabling its customers and partners to succeed in theirs. Having a focused, agile API makes it easier to establish your dominance in your market and maintain this status into the future.

Netflix

Netflix is an example of a company that has established market dominance in the video-streaming industry based on the use of its API by different consumer video devices. It has innovated and changed its API to remain the most dominant system in the movie-watching industry—from integrations with partners that make DVD players, to online movie rating and ticketing services. Netflix’s main business value is dominating its industry by enabling integration with devices within this space to increase its user base and provide value to its existing users.

Netflix tuned its API to make it highly usable for devices such as consoles, DVD players, televisions, tablets, and smartphones. It removed the parts of the API that weren’t important for these partners or germane to their current system—such as the DVD queue and search APIs—leaving a tightly tuned set of APIs that it offers to these device companies. Netflix restricts its partners to platforms that will reach tens of thousands of its own subscription users. In addition, the products provided by Netflix itself, including its phone, tablet, and desktop computer applications, use the same APIs they provide to these device manufacturers. Everything is highly optimized to allow users to have a high-quality browsing and viewing experience, whatever platform they’re using (see figure 6.7).

Figure 6.7. Netflix is an excellent example of how an API can streamline a user’s experience. The API itself provides basic search and information about movies, including people and genres associated with them. The company additionally provides a movie player on most major platforms, which is integrated with the Netflix platform via the API, so a user can always find and learn about movies before watching them. The API makes it possible for other devices and applications to do the same thing so that users’ experience is consistent across all the applications they use.

Netflix has been so successful in this space that creating a movie site or new video-enabled device without direct Netflix integration places a potential video-viewing product at a disadvantage. The reach and established base of the Netflix API is so strong that all new entrants to the space are compelled to integrate with Netflix, and existing vendors are highly unlikely to remove or replace Netflix in existing products. This is not to say that these device companies won’t add other video-streaming services, but excluding Netflix reduces the value of a product in a significant way. Device manufacturers and movie sites are motivated to partner with Netflix and to continue doing so to maintain their own place in their specific industries. The synergy between Netflix and device manufacturers enhances both of their places in their relative industries.

6.2. Metrics

Once you’ve determined what your business value is and what you’re trying to achieve with the product, it should be relatively easy to determine how to measure the success of your platform in this area. Frequently, companies are tempted to create metrics demonstrating the reach of the API without demonstrating how it’s adding to the bottom line. Metrics such as “number of developers who have signed up for the API program” and even “number of calls to the API” aren’t going to be compelling to the executive team. Although API usage statistics, including applications and users, can show that the system is growing to be able to provide the value desired by the company, the most meaningful metrics are those that demonstrate how the platform is contributing directly to the established business value.

6.2.1. Poor metrics

For any API, the most common initial choice made in creating and tracking metrics is to track the number of developers who have signed up for an account within the system (see figure 6.8).

Figure 6.8. When determining the success of your API, the simplest things to measure are the number of developer keys and/or number of calls. Without measuring the types of calls or number of end users, these pieces of data aren’t at all indicative that the API is creating value for your company.

In the case of these metrics, the analysis will not help you translate the activity into the business value you’ve already determined. It would seem that the number of calls is a good thing to track, and it’s a fine internal metric for the API team. But when communicating with other groups outside of the development team for the API, your business goals need to be broken down into metrics that are more meaningful in the context of your value proposition.

A member of your executive team may initially be interested in the general usage of your API, but in the medium and long term they’ll want to see how the API is contributing to the bottom line of the company. An API that’s not showing success in other areas is costing money for the company with no obvious path to creating success, so you need to share metrics that demonstrate how the API is improving success for the entire organization or face the chance that your API will be deprioritized by the company.

6.2.2. Monetization

When the API is your main platform, you can easily measure success by looking at the revenue generated by that product. In many cases, though, you can target growth for your product by watching related analytics to determine how well your system is scaling and helping you fill the pipeline for future success. In the case of a company like Twilio, for instance, it probably wants to figure out which metrics speak most clearly to its platform’s ability to continue growing. Figure 6.9 demonstrates how a company like Twilio can effectively measure performance and progress.

Figure 6.9. As a system with an API as its main product, Twilio can easily measure things that demonstrate API success. It can measure standard company metrics like revenue per employee, because all of its revenue comes through the API. Additionally, it can measure things about the accounts such as the number of conversions to paying accounts and the number of accounts with a high and consistent volume of calls.

Even for a company where the main product is the platform, the easiest things to measure are of limited use to the company in terms of projecting growth and revenue. Measuring the number of people who have signed up or the number of calls per month (which includes a significant number of “free trial” calls) won’t help the company become more successful over time. Focusing on the exact items that can improve the business value you identified is tricky, but worthwhile.

The easiest data to measure in Twilio’s case would be revenue-per-employee, as there’s only one product to consider. Yet this doesn’t help plan for the future or use metrics to measure not only past and present success but future revenue. Revenue-per-customer would be better (because it would include newer customers), but is still too indirect to help identify what needs to happen to drive future improvements.

Because Twilio is striving to be the market leader, introducing new developers to the system is important. But many times developers may not use Twilio beyond their initial introduction to the system, usually at a hackathon or conference. These developers don’t contribute to the bottom line of the company. How, then, could Twilio measure success?

Twilio provides all new developers with a decent-sized allotment of money for their initial calls. So, are developers who recharge their accounts from their own money more likely to go on to continue using the API into the future? If so, the number of developers who convert to paying customers could be a good thing to track.

The company is also interested in increasing the volume for existing applications. The army of developer evangelists is an awesome way to drum up awareness and interest in the platform, but real money is made with customers who create a steady stream of revenue over the long term. This being the case, the number of high-revenue customers—customers over a certain volume of calls per month—is something that’s important to keep track of.

6.2.3. Usage

When determining metrics for usage, a company needs to dig a little deeper to determine the measures and statistics that will be meaningful for the company itself. If the goal is to increase usage, that’s a relatively easy measure. But you might extend this a little to capture your goals.

Do you want to measure writes to the API as a percentage of overall updates to your system? Is signing in with the social system valuable to your company? This gives you identity management for your users, keeping them connected to your system even when they’re not directly interacting with it. Figure 6.10 lists a few ways you could measure the performance of a platform that’s heavily directed at increasing usage within the system.

Figure 6.10. Social platforms have a specific set of goals; increasing the amount of activity in the system and the frequency of interactions by users both indicate a healthy ecosystem. When determining strong metrics for your social application, think carefully about what kind of metrics will indicate that users are more closely tied to your system (frequency of interaction) or providing new interesting content (frequency of writes).

6.2.4. Partner retention

This business value is more difficult to measure than the previous two choices. How do you measure the success of a platform that’s aimed at maintaining partnerships with your customers? The overall effect on your bottom line will be adding stability and growth to the number of customers using your main product. The value here could be derived from the number of customers using the system who continue to use it for a set amount of time into the future. You could measure the percentage of applications that are still active 3, 6, or 12 months into the future and determine how successfully you’re retaining those valuable partnerships.

Using FedEx as an example, the company is in a highly competitive industry. UPS and the USPS, as well as countless smaller shipping and logistics organizations, compete directly with FedEx to achieve and retain the status of primary shipment company for their customers. The ability to integrate the shipping, tracking, and logistics information into customers’ applications with a minimum of fuss is quite important.

6.2.5. Market dominance

When working toward market dominance, you want to measure the reach of your platform and your position in the marketplace relative to your competitors. This type of metric is much more in line with the metrics frequently considered important by businesses.

Netflix is a great example of this type of measurement. As the DVD business waned, it became critically important to establish a position of dominance in the market, and several other competitors were entering the space at the same time. Netflix started early on this strategy, partnering with video device and game console manufacturers to make sure their users could watch Netflix on whatever screen they were near.

To measure the success of this strategy, Netflix might track the number of devices it appears on compared to the devices’ relative position in electronics sales. Netflix is selling a service, so the amount of time a user spends watching movies increases the value proposition for that user. It could also measure the number of hours users are watching movies on its devices.

6.3. Use cases

In chapter 5, I mentioned use cases as something critical to the success of an API. In this section, I describe how you can map your business goals to your design and development phases. Once you’ve determined your business metrics and how you’ll measure them, it’s time to think of use cases that will help guide you to increase those metrics in the way that’s meaningful for your platform and that will support your business goal. Don’t be shy during this part of the process; think about exactly the kind of use cases you want to support and make those workflows as easy as possible.

6.3.1. Mobile

Although this isn’t one of the business goals I mentioned, mobile is a use case that almost every API designer should consider. It’s one feature that’s hard to add after the fact, so you need to design with the mobile developer in mind so you don’t end up having to refactor your code even before the platform is released.

Mobile is a tricky case (see figure 6.11). As I’ve said, developers who are creating mobile applications need to be able to make minimal calls for the system. Back-end calls to your platform must be quick and efficient. The more calls the end users can make, the more revenue your system will generate.

Figure 6.11. Basic mobile interaction. Without focusing on the specific information in the call, an initial call from the client to the platform will include authentication information and specifics about the resource being requested. On the platform side, the authentication data will be processed by the auth segment of the platform, and if the credentials are authenticated (who is it?) and authorized (can they do the action?), the request is passed through to the platform, and a response is sent back to the client.

For each of the actions in your system, it should be extremely simple, in a single call, to do the following:

• Authenticate or verify credentials for the user
• Make a complete call to your system, returning exactly the data needed by the application
• Provide the ability to gather all information for a screen, or accept all the information needed for an action, in a single call

Mobile, more than most other use cases, requires mindful development and sometimes requires additional work to make it successful. But mobile usage is one of the main uses for an API, so it’s worth your while to make these calls as easy as possible. Remember, any time you’re faced with a decision to improve usability or reduce development use on your side, the right call is almost always to make your system easier to use.

6.3.2. Monetization

When your API is your main product, monetization must be the business goal for your platform. You can achieve this in various ways: usage-based, subscriptions, or other mechanisms. The trick is to make sure that the client developers get enough perceived value out of your platform to justify the expense.

Twilio

In the case of monetization, it’s critical to make it extremely easy for people to interact with the platform in whatever way makes sense. You want people making as many calls as possible, so you want to make it easy for your customers to make calls from mobile, desktop, or sharing applications. Ideally you’d support all these use cases, with easy-to-use interfaces that support all user models for your direct customers, the developers.

As an example, Twilio supports (among other things) sharing out to multiple friends using SMS, sending voice messages, creating conference calls, and handling video. Twilio’s main value to customers is that it makes telephony easy. If you have ever tried to create a system for interacting with a telephone network, you know how difficult and time-consuming it can be, and when application developers are working on their own, it’s nearly impossible to get a contract with those systems for top-tier service and support.

Here are some example use cases for a telephony application of this type: using easy authentication, performing quick single-call interaction, sending SMS messages to multiple friends or a group, sending a voice message to users, or creating a group conference call. Although it’s clear that sending information to users could use push notifications, SMS and voice are two modes that are much more immediate than push notifications to grab their attention. It becomes easy to use SMS as an immediate chat channel for a group of people, to grab people’s attention when they’re near someone they know, or to seamlessly alert users that someone who shares their interests is nearby. These would be great supplements for a social/dating system. Twilio also makes it easy for people to opt out of these interactions easily, so the client developers don’t have to worry about that aspect of this interaction.

SendGrid

SendGrid is another company that makes hard things easy (see figure 6.12). Most companies need to use email to interact with their users—sending out alerts when important events have happened, initiating a user verification or password reset, or sending announcements about activity within the system. SendGrid is designed to manage all aspects of sending mail. It has white-listing and prescreens all customers to make sure the system is clean and not sent to junk mailboxes. The scalability is baked into the system, freeing customers from needing to be concerned with email growth. All transactions are as secure as possible. Metrics are strong and targeted at transactional email and marketing campaigns. SendGrid has demonstrated its value for companies like Foursquare and Ladders, both successful companies that started out having their engineering team attempt to manage the high volume of email required by their business model. SendGrid has made it extremely simple to manage the email that your company needs to send and track. In this case, the use case is making mail simple and quick for their users.

Figure 6.12. The SendGrid platform is like a central routing station for email interaction. It can schedule and structure outgoing emails to provide for tracking clicks, bounces, and spam filtering. The user interaction with the system is simple and straightforward.

The APIs provide the ability to get real-time event data such as bounces, clicks, and spam reports. SendGrid provides several different interaction models for its customers so that they can use whichever protocol works for them, whether it be SMTP (Simple Mail Transaction Protocol, a standard email protocol for the web) or the web API. Several different functions exist within the APIs designed to support marketing or transactional use cases, or to integrate more deeply with the system.

SendGrid realized that email is frequently something that needs to be triggered by an application action or system event, so it made automating transactions with webhooks (a relatively simple system) possible, as well as providing the ability for developers to integrate deeply into their own system to support their own needs.

Context.io

Context.io also works with email, but instead of focusing on sending emails, enables access to information in your users’ inboxes as if they were databases (see figure 6.13).

Figure 6.13. Context.io creates a database out of an email box. The contents of the email box are read, and functions are exposed for searching, filtering, sorting, and formatting that data. Additionally, when changes are made in the data by Context.io to add tagging or other additional information, Context.io writes these changes back to the originating email box.

It supports queries on the mailbox and allows you to query by keyword, user, or thread. Additionally, it will POST back to your server information about actions in the inbox, allowing you to configure actions that can trigger webhooks to do whatever you want. Again, in this use case, the company is working to make something that’s challenging easy for anyone wanting to analyze the data in a user’s mailbox to create valuable metrics, track and report specific actions, and work with email the way users tend to do: by thread.

Monetization is a great business case when a company is striving to make difficult things easy for developers. Any time someone can offload a needed functionality to another company that provides useful actions for the money, it’s going to be a great value for companies wanting to focus on their core competencies rather than expand their engineering team to re-implement functionality that can be purchased elsewhere. In all of these cases, the monetization metrics of “calls per user” or “growth over time” are easy to understand when the success of the company is tied to making critical functionality easier and more reliable.

6.3.3. Usage

Usage tends to be a business value well suited to social applications. There are many such systems; Twitter is the most obvious, with Facebook and Tumblr also providing interactive functionality for millions of users. Whichever system you’re working with, there are two critical actions you want to be able to support with simple interfaces: writing to and reading from the stream. Each system features other interactive actions that are tied to the specific goals of the company. In this section, as I discuss each of the companies that are focused on social interaction, I’ll discuss their main use cases as examples.

Twitter

Twitter, for instance, doesn’t provide complex profile data, games, or other interactive applications. Writing to the activity stream is the most valuable interaction a user can provide for the system’s business. To encourage application developers to write status updates to the system, Twitter implemented the items shown in figure 6.14.

Figure 6.14. Twitter has examples to help understand how use cases are mapped to API functions. For each of the examples listed here, the interaction point provides benefits for both Twitter and the end user. Great APIs will always create this kind of mapping—if an API improves the end-user experience as well as improving the system itself, it’s most likely to become successful and well used.

Twitter doesn’t charge for this service, which encourages application developers to help Twitter users to add new content to the data stream, keeping it fresh and interesting.

In addition to writing to the system, Twitter wants to add even more value by making it easy for client developers to enable Twitter’s users to read from the system and track things of interest to them. Users can retrieve information in a few different ways, all easy to do via the API so application developers can match the ideal activity stream with the use case they have for their own application.

The main type of read access client developers can offer to their users is status, or timelines. Users can see their home timeline, which is what they see first when logging into the Twitter application itself. In addition, they can see another user’s status, mentions, or retweets. All of these are individual resources within the application, and quite easy to access. Application developers can also provide their users with the ability to read and write direct messages.

There are some more complicated interfaces in the Twitter system. Search is necessarily somewhat more complex. The application needs to create a query to communicate exactly what type of search is being made, and building this query is more complex than the retrieval of a single, well-defined piece of data from the system. Similarly, an application can access the streaming API to watch for new posts that match a particular query.

In fact, because Twitter runs completely on its own API system, client developers can provide virtually all of the Twitter functionality to offer users within their own application.

Facebook

Facebook has a much more complicated system to offer to users, but the first and most popular is the Wall, which provides the activity stream for client developers to integrate into their application. Writes and reads work much as they do for Twitter, and searches are available as well. There are widgets for reading from and writing to the activity stream.

But Facebook’s system is much more complex than Twitter’s. Although Twitter encourages application developers to create applications outside of the system and post updates inside Twitter, the sharing of game or application activities is discouraged. Facebook encourages application developers to create games or other applications designed to run within the Facebook ecosystem and write to users’ walls so that other users are encouraged to play. Facebook even provides a system allowing application developers to charge users for game enhancements.

The widgets offered by Facebook allow for much easier implementation of certain types of functionality, particularly social interaction. Facebook even makes it easy to add Comments, Likes, and Shares to your own web pages with the installation of a simple plug-in on your site. By simplifying its API even further for these types of actions, Facebook makes it extremely simple for content providers to leverage the Facebook system to enhance their websites without writing any code.

Although I don’t tend to like SDKs for simple REST APIs, I do appreciate the SDKs provided by Facebook. These tools are designed for a few things:

• Assist developers in creating applications that can be accessed and played outside of Facebook
• Allow developers to use Facebook to make the games or other applications more social
• Allow developers to leverage the money-making functionality Facebook offers to developers

In short, Facebook provides several types of APIs for integration. Simple widgets allow content providers to integrate social sharing and conversation around their content without writing any code. The REST APIs, including the Graph API, allow developers to leverage the complex Facebook social graph for use within their applications. SDKs assist developers in creating applications that can utilize the monetization and social interaction from Facebook in applications residing on other platforms.

Tumblr

Tumblr is a super simple blogging platform, allowing users to post media, such as video or photos, thoughts, or replies to other posts. Many application developers have found new and interesting ways to utilize the functionality provided by the Tumblr system. The simple API makes the system quite interesting; several applications use the system to create their own blogging or photo-sharing application on top of the Tumblr platform. Tumblr can be considered, at its heart, a sharing platform for users.

Tumblr has gone even further than other social applications in simplifying authentication. Just as much of the content is available without logging in on Tumblr, certain items can be accessed without any authentication in the API. For instance, getting the avatar for a user can be accomplished by a bare call to the avatar endpoint for that user, without any credentials at all. Many of the calls can be made with a simple call, identifying only the application making the call, but not the specific user retrieving the information. Making these calls simple means that an application could be created that never requires a login by the end user. This system is designed not only to be easy for users to interact with directly, but to encourage applications to provide simple access as well.

The simplicity of this system, both via the web interface and the API for developers to integrate with their application, reduces the friction in adding content or including it alongside other activity streams.

6.3.4. Customer/partner retention

Partner retention can be one of the most valuable goals of a company’s platform. If you can make it valuable for partners to continue using your system once they’ve integrated—and difficult to replicate that information with other systems—you’re adding friction to the process of integrating with your system. This retention can be created in multiple ways; I’ll mention a couple of different examples so you can have an idea of what kinds of things will make partners think twice about jumping to a different platform.

Unique content

When you have a specific type of functionality that’s unique to your platform, it becomes a compelling reason for partners to integrate with you and also creates some reluctance for them to remove that functionality. An example of this is LinkedIn. This business-focused social platform provides several pieces of valuable functionality available only to partners.

Flipboard largely uses the LinkedIn functionality to get users’ activity and their news stream from LinkedIn, which has one of the best user-targeted article ecosystems out there. Removing LinkedIn from the application would lower users’ satisfaction with the system, so Flipboard is unlikely to want to leave the system. Additionally, though multiple news-focused systems are out there, few of them provide the user-centric newsfeeds available via LinkedIn.

Hootsuite is a social system that schedules and batches updates to various social systems, including LinkedIn, Twitter, and Facebook. The main use case for Hootsuite is business, and its pricing structure is designed to help companies manage their social media strategies. If Hootsuite were to remove this dominant business-focused social platform from its application, a great deal of its value to users would be eliminated.

Automation/integration

Many companies provide services for their partners and customers. As time has gone on, more and more companies are providing Software as a Service, Platform as a Service, and Hosting as a Service. No matter what service is being provided, the configuration, metrics, and automation for the system is critical to a healthy relationship between the provider and the customer.

Amazon and Rackspace provide various hosting platforms. Akamai provides content-delivery services for companies wanting to improve their web performance. All of these, as well as many other hosting platforms, have APIs for their customers to use to integrate configuration and reporting with their own systems. This provides customers with the ability to track data from the service into dashboards they have for their own functionality, automation for alerts and events, and the ability to integrate frequent actions into their own systems. For instance, Akamai allows customers to add cache purge functionality to their content management systems.

When you’re providing a service for your customers, frequently you can encourage them to integrate your administrative functions into their own systems. This integration generally requires development resources from the customer, and as a result the customer won’t be inclined to redo this work to move to a new provider. Those APIs must be reliable, scalable, and usable. This is a case where moving to an API First system works in your favor, because those administrative functions will be available to your customers, to integrate at whatever level works best for them.

6.4. Summary

To wrap up this chapter, I want to point out that these items are critical to creating a healthy, successful API. Without knowing what your business goals are, without knowing what metrics you’re going to track, and without setting up strong use cases to drive those metrics and value, your API is not likely to make it. These items are required when creating any other product for your company, and your API is no different. The process for working through these steps is as follows:

• Determining your business goals— This is critical for any product, and an API is no exception. Determine how your API product will contribute to the success of your company.
• Defining your metrics— Once you’ve determined the business value, spend some time considering how you could measure the activity of the API to provide meaningful insight into the progress toward the business goal.
• Creating meaningful use cases— Now that you know how to measure the success of your API, it’s time to create use cases that support those values and metrics.

The next chapter covers the process of modeling the schema for your application. We’ll explore two of the main schema modeling languages, OpenAPI and RAML, and talk about ways to approach the modeling based on the use cases you’ve created. We’ll also discuss the value of schema modeling for improving the clarity of your conversations with customers and other teams, and I’ll use these schemas as a basis for guiding your development strategy in future parts of the process.