Chapter 9. Empowering your developers

This chapter covers

• Pillars of developer experience
• Clear communication
• Documentation
• Building blocks
• Support

Once your API is ready to be released into the wild, you may think you’re in the home stretch. But the success or failure of your API will hinge much more on the developer experience you provide than on any specific technical choice you’ve made. Developer support sometimes takes a back seat to new development projects, but in the case of an API, where you’re working with developers outside of your team, it’s critical that you create an experience that truly shines.

After reading this chapter, you’ll have an entire system for the development of your API, with several checkpoints throughout to help you make sure you’re still on track to building the API you’ve envisioned.

9.1. Pillars of developer experience

When your team thinks about developer experience, it may be tempting to pay less attention to internal APIs that other employees are required to use than you would to an external API for use by external developers. This is a fallacy: anyone who’s going to use your API needs excellent support. I’ll help you understand the value of spending time and resources getting this most important piece perfect. Providing the right experience for your developers works for you in multiple ways. The trade-off always comes down to cost and speed for your team as opposed to goodwill among your customers. Figure 9.1 shows the pillars of API support required to create a great customer experience. I cover these in more detail throughout the chapter; this quick overview is to help you understand how the pieces fit together to create a fantastic developer experience for all of your client developers.

Figure 9.1. The four pillars of API support are communication, documentation, building blocks, and support. Every one of these pillars improves your client developers’ understanding of the platform, and with that understanding comes engagement and integration.

For external APIs, it’s clear that you need to make sure your developer customers understand the API, can use it successfully, and don’t get stuck. You want to ensure that they understand how the API should be used through use cases and comprehend the guidelines for working with the APIs. Guiding your customers through an excellent developer experience—outlined in this chapter—will create happy and successful developer customers. But that’s not the only advantage to your team. Those customers will help other customers to be successful. They’ll be able to get started and extend their applications with minimal help. Seeing that the developer experience is a priority will encourage new developers to give the system a try.

For internal developers, who may be required to use your system, it is still critical to provide a fantastic user experience. If developers are forced to use a system they struggle with, they may try to work around it, implement inefficient and unsupported workflows, and generally create a support burden for your team.

This chapter covers the steps required to create a phenomenal developer experience. It may be tempting to cut corners or skip some of the pieces. I strongly encourage you to reconsider the costs this can create in extra support and developer confusion. Some of these items align more closely with an internal or external API, but in reality they’re all important in both cases.

9.2. Communicating with your developers

In general, companies and organizations want to keep their vision and strategy close to the chest. Revealing this sort of information outside of your development organization feels like a vulnerable choice, but it’s critical for a new platform, or an existing platform, to provide as much context around the API program as possible. I’m not talking about reference documentation, tutorials, and example code. For this high-level communication I’m referring to things like the overall vision, business values, and metrics.

9.2.1. Failures of communication

I’ve worked at two different companies, Netflix and LinkedIn, where information about the business goals for the API weren’t shared. Additionally, I’ve spent a great deal of time studying the trials and successes of Twitter. In the first two cases, poor communication, 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 its API was so strong it could weather the storms it 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, nonthreatening face. Part of this was designed to “let a thousand flowers bloom,” the thought being that with 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 fully formed from the uses of the platform. But what happened over time was that these thousand flowers didn’t bloom. The company decided that the third-party developers using the API weren’t 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 didn’t go away.

But the third-party developers weren’t creating revenue for the company, so the decision was made to phase out the API. This decision made sense from a business standpoint, and it was certainly the right decision. Netflix even went through the trouble to phase out the open API gradually. This was not communicated to the developer community, though. 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. Few missives were sent out to help developers plan for the eventual sunset of the platform. As a result, a number of developers 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. Although the developers working on the platform were talented and 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 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, who were left to deal with a slowly contracting set of APIs available to them. Business partners with close contractual ties to LinkedIn were given access to the original APIs, but this excluded third-party developers, an action that fomented a lot of discontent among the developer community.

Twitter

Twitter started out without a great plan for its API. It began 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 its 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 it 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 didn’t do a good job of keeping developers informed about the changes in its strategy, leaving a plethora of dissatisfied developers. Their developer base is incredibly strong and so Twitter weathered the problems. Twitter has become much better recently at sharing their company direction, with blog posts and press releases and presentations at their conferences.

9.2.2. Strong communication

Whenever you have an open platform, communicating openly with your developers is critical to the success of your APIs as a whole. Although 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. It has a multitude of APIs, which cover everything from mapping to calendar functionality. Some products in this pipeline don’t succeed, and Google makes the decision to sunset the APIs in order to place its resources on other, more promising products. Developers who work with Google APIs can have confidence that they’ll be informed via email, blog posts, and documentation updates as soon as the priority for the API changes within Google. Google has met with a great deal of animosity over the choices it’s made in retiring old APIs, but treating its developers like adults who can understand business decisions gives Google a good reputation as a strong communicator in the API industry.

9.2.3. Advantages to strong and consistent communication

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 nailed this piece of the developer experience puzzle, but in my 10 years of working with APIs, I’ve 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.

For 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 % 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 versus through the main product
• Number of applications interacting via the API
• Number of new users coming through via third-party applications

To communicate this with your customer developers, the information has to be clearly available for them to read. The wording must 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-speak,” 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 the access methods for the API are given equal importance, and there’s no feel for what it is that the company wants to accomplish with the platform. No examples are given about what the API could be used for. If developers don’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 have a strong message about what the API was created to do, and what the company wants to accomplish with it. This is that 10-second elevator pitch discussed earlier, where you have a 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 find more ways for users to interact with our application. We’re measuring our success by enumerating the applications with consistent, heavy usage of the type we desire—whether that’s reading or writing. 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’re 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 have unique content be 20% 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 its success.

Obviously the 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. Avoid sales-speak at the abstract level and instead tell developers 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 in a flat, reference documentation way. Although reference documentation is indeed important, your documentation can’t stop there, because developers outside 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 description doesn’t need to be as detailed as a tutorial would be (although these examples will likely also be in the tutorials you provide later). You need to explain what the use cases are and provide a high-level description of how tasks would be accomplished using the APIs you’re providing.

Here are a couple of examples of the kind of information that should be included on the page describing your overall API strategy:

• 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. Here are some examples:
  • Using the “user” API, you can get customized information about users, such as their full name and photo, 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, 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 new information to the timeline based on what users 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. Here are a few ways this could be used:
  • 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 users are reading through a different interface for data, such as a magazine or news highlight application, that application 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 that shows which of your users’ 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.

9.3. Documenting your API

The second pillar of developer experience is documentation (see figure 9.2). Documentation covers a wide range of different methods to help developers understand the platform, work with it, and succeed in integrating the API into their own system.

Figure 9.2. Documentation takes many forms, and it’s critical to understand that reference documentation—what each endpoint does, and what the requests/responses look like—is only the beginning. Developers need to understand workflows for complicated chains of requests, and tutorials and guides are also critical to helping them understand the entire system more clearly.

The types of documentation you need to have are as follows:

• Reference documentation— “What does it do?” This is the documentation you’re probably expecting to need. You’ll be answering more specific questions such as “What does each endpoint of the platform do?” “How does a developer call it?” and “What is the expected response to a call?”
• Workflows— “How do I do something with the platform?” This type of documentation tells a developer how to achieve specific tasks using the platform.
• Tutorials— “How can I get started?” These tutorials should take your specific targeted use cases and create step-by-step guides for developers to follow in order to get started using the system, or achieve common, simple tasks. Usually the tutorials you should include are the most important items from the workflow list.

9.3.1. Reference documentation

Reference documentation is the “standard” documentation you’ve likely seen for APIs: a list or other way to see each of the endpoints for the platform along with a basic description of what each endpoint does. This documentation is frequently done poorly, with only a skeletal description that’s difficult for outsiders to understand. Even though the reference documentation isn’t going to cover all your needs, doing a great job on it is vital. When developers can’t figure out how to interact with an endpoint, or with the system itself, they get frustrated quickly and your support load increases dramatically.

This section explores how you can create effective reference documentation and the advantages of each approach.

Bare minimum

At a bare minimum, reference documentation must have the following:

• A catalog of endpoints to find the resource a developer is seeking
• Clear instructions on interacting with the system itself:
  • Header information
  • Authentication
  • Error codes
  • Any other general information a developer will need to make a successful call
• For each endpoint, the following is required:
  • The exact endpoint for the call
  • How to make a successful request
  • What a response will look like

Building this kind of documentation takes more time compared to much of the API documentation out in the world, but without all these items, you’re leaving out information that’s needed in order to figure out how to use the system. Honestly, it’s frequently difficult to impose a requirement on developers to create excellent documentation. To provide this bare minimum of documentation, you can help your developers or technical writers by creating templates so that they can see exactly what’s expected and required for each endpoint. It doesn’t matter how you create this documentation or how you present it as long as it’s understandable without any additional context.

Providing opportunities to explore the API

Once your reference documentation has the basic necessities, strongly consider providing a method for exploring the API. This can be done in various ways:

• All the major schema modeling frameworks provide documentation that includes all the bare minimum requirements listed earlier along with the ability to interactively explore the endpoints without writing code and making live calls. For reference, the schema modeling frameworks I covered earlier were RAML and OpenAPI.
• There are some independent systems, like I/O Docs, that allow you to document your API and provide interactive exploration without using a formal modeling system.
• Companies like Apigee include an interactive exploration console as part of their API management offerings. The console provided by Apigee allows for simple authentication and makes live calls against the database for the user.
• If you choose to use hypermedia, you can provide a simple tool that uses those references to find related information, creating a different method for exploring the API.

Whatever path you choose, providing this kind of exploration tool will

• Help your developers answer questions about which endpoint they want to use
• Show them what a successful call looks like to a particular endpoint
• Build a strong mental model of what your overall platform looks like

When your basic reference documentation implements an exploration tool for your customer developers, it improves your developers’ experience immeasurably and reduces your support burden.

All platform providers have to have some basic reference documentation available, and frequently their documentation doesn’t even reach my bare minimum requirements. Keep in mind that you want your API to stand out for positive reasons: you want it to be easy for people to figure out which endpoint to use for a particular purpose, and you want developers to have confidence that they can use other endpoints, knowing that the documentation will give them a solid understanding.

9.3.2. Workflows

Now that we’ve covered the question of what each endpoint does and how the developer should work with it, it’s time to answer the question of “How do I do something with your platform?” This question is rarely answered with a single endpoint; most endpoints need to be used together to create a meaningful integration into the platform. Enter workflows, the best way to answer this question for your developers.

A workflow describes, briefly, the steps needed to use a particular endpoint to retrieve information (see figure 9.3). It’s frequently the case that one endpoint isn’t usable without first calling other APIs to retrieve parameters to pass to that endpoint.

Figure 9.3. Getting an Akamai Billing Usage report from scratch can be somewhat daunting. You need to call three different API endpoints to get specific information in order to make the final call. Creating sample code or documenting workflows can help users get past this type of challenge with minimal frustration.

Here’s an example of a workflow similar to many instances I’ve seen in the past:

Goal: Get a billing usage file for all products for an account

• Call one endpoint to retrieve the ACCOUNT_NUMBER.
• Using the ACCOUNT_NUMBER, call another endpoint to retrieve the PROPERTY_ID.
• Using both of these parameters, call a third endpoint to find out which PRODUCTs were active during a particular time period.
• Finally, call the billing endpoint using all of the previous pieces of information.

This workflow isn’t particularly complicated. It’s flowchart information describing how to use the API to retrieve information, but without this kind of additional information, it can be extremely confusing for customers who aren’t sure where they should be getting these required parameters from.

Note that there’s a goal at the top. Each of your workflows should describe, in narrative form, exactly what the goal is for the workflow you’re including. It may, and probably will, seem painfully obvious to you and silly to include this information, but include it anyway. Your developers will thank you for the ability to scan through the workflows and find exactly the one they want, using the goals at the top of your examples.

Although your tutorials can be focused on the main use cases for the API, you need workflows for every set of endpoints to make sure that developers don’t flounder around looking for the information they need. Even if the information they need isn’t in the API, tell them that. It’s never a bad idea to add more helpful documentation for someone who’s trying to use your system.

Workflows are the cornerstone of your platform, demonstrating the various ways users can interact with the system. These workflows must be easy, straightforward, and understandable. This is a good time to talk about usability testing. As an industry, we’ve done an increasingly good job of testing the usability of systems we create. But the same can’t be said for API developer interfaces. When you’re pretty sure that you’ve got the workflows covered, it’s a great idea to get people outside your group to try to work with each of the APIs you have, following the reference documentation and workflows that you’ve provided.

9.3.3. Tutorials

When my current company wanted to redo its developer portal, we reached out to the current developers and asked them what they’d like to see on the site. The overwhelming majority of the respondents replied that the thing they needed most was a Getting Started section to work through. Creating and adding this tutorial to the system increased the number of developers working with our system significantly, and we spent far less time answering simple questions from new developers.

Tutorials are one of the best ways to help developers ramp up on knowledge about your platform. In addition, creating these tutorials based on your most important use cases gives you an opportunity to help your developers understand how you want them to interact with the API.

Before I demonstrate how to write an excellent tutorial, here are some guidelines for creating these guides:

• Do not assume any specific level of knowledge for the readers.
• Have someone with excellent writing skills write the steps if at all possible. The tutorial will need to be more narrative than the reference documentation or workflows.
• If you choose to provide the tutorial in both text and video form, make sure that both stand alone as excellent narratives. Don’t slight one in favor of the other; developers learn in different ways and you want to make sure the experience is great either way.
• Break down the steps into separate pages. Give each step a beginning (goal), middle (technical content), and end.
• Provide sample code that follows the tutorial so that developers can follow along without cutting/pasting or retyping code, allowing them to move more quickly and focus on understanding what’s happening in the step. In terms of language to use, it’s great if you can provide different programming languages, but if not, be considerate of students who might not be familiar with the programming language you choose.
• At the end of each step, give the student a virtual high five for having accomplished the task.
• Tie related tutorials together in a Choose Your Own Adventure presentation to encourage developers to work through multiple tutorials in a row and get a good, deep understanding of the system.

When creating a Getting Started tutorial it’s quite important to realize that this tutorial aims at developers who are not at all familiar with your system. Everything you can do to make this more accessible for your readers is helpful. My experience with the tutorial we’ve made, which is now quite well received and meets most developers’ needs, was this:

• I started out with a simple Python code sample (shown later in this chapter), and we made step-by-step instructions for how to implement it.
• The authentication steps turned out to be difficult for developers to follow, so I added a new script to simplify the integration of authentication information into their system for use by the sample code.
• We discovered that on Windows boxes, the SSL implementation in Python doesn’t work in versuib 2.7 (except in Cygwin), or in Python 3.3, so I had to come up with another way for Windows users to work through the Getting Started tutorial.
• I created a Docker container (as I did for this book) so that the developers could pull the container onto their system and follow along with the examples, and also use the other sample code in the repository.

The acceptance tests created in chapter 8 are a great place to get outlines for your tutorials. One of the examples from that chapter was as follows:

Acceptance test case: Add new pizza topping

• Get a list of pizza toppings in the system
• Verify that the new topping doesn’t exist
• Add a new topping to the system
• Get the list of pizza toppings
• Verify that the new topping has been added

Getting started: introduction

To get started on a tutorial, you’ll want to write a short introduction to it. Restating the acceptance test in this section is an excellent idea, because it gives the developer the opportunity to know which steps are included. Start out with a summary of what task the tutorial is modeling for the student.

In this tutorial, you will be adding a new pizza topping to the system. To do this, it’s critical that the system is checked to verify that the topping isn’t already there. Additionally, you will check the topping list after adding it to make sure that the topping has been added correctly. The samples will be created in Python, but the code is quite well commented and runs as written. Rather than focus on the code itself, focus on the concepts in the tutorial.

This simple introduction helps to add context for developers. They’ll understand what they’ll be doing, and it should make it quite simple to follow the instructions.

Individual steps

Each step should be presented on its own page, although you can combine two related steps into a single step that’s slightly more complicated. For this example, I’ll merge “Get a list of toppings” and “Check to make sure that the topping doesn’t exist.” This example will be in Python, but I’ll comment the code clearly. The reason I use Python for my example code and tutorials is that it’s the easiest language to read if you don’t know the language yourself. It reads similarly to English, and when you’re creating code samples for tutorials or other learning, you can increase the readability with code comments and clearly defined variable names.

GET /api/v1.0/toppings

{u'toppings':
      [
           {u'id': 1, u'title': u'pepperoni'},
           {u'id': 2, u'title': u'peppers'}
      ]
 }

#! /usr/bin/python

# Create a variable to hold the topping name
topping_to_check = "Sun-dried Tomatoes"
topping_in_list = False

import urlparse as parse
import requests

# Create an HTTP session for making requests
session = requests.Session()

# Make the HTTP request to the toppings endpoint
toppings_result =
  session.get("http://www.irresistibleapis.com/api/v1.0/toppings")

# Transform the result from JSON into an object for the "toppings" item
toppings_list = toppings_result.json()["toppings"]

# Iterate over the topping list to check for the specific topping
for topping in toppings_list:
    if topping["title"] == topping_to_check:
        topping_in_list = False

if topping_in_list:
    print "In List"

else:
    print "Not in List"

In this example:

• I gave an exact example for what comes back from an API call.
• The code sample is simple and straightforward.
• I didn’t use any fancy functions or abstract concepts, and I added a healthy number of code comments.

At the end of each step, congratulate the student for having accomplished the task in question. And after all the steps, summarize the task again and how it was accomplished. Then point students to other tutorials they might want to move forward with to continue their exploration of the system.

9.4. Building blocks

As I’ve mentioned, marketing to developers is not like marketing to other people. As developers, we like to see examples of things and be given building blocks to work with. Most developers I’ve met would rather stick a fork in their own eye than read through a PowerPoint presentation or sit through an abstract “Buzzword Bingo” meeting without any hands-on content. You can choose among several different ways to provide a coder with pieces to build from, or show them how something works from the code side rather than showing pictures to describe the overall effect. Detailed, hands-on toys that allow developers to build working models are the best way to reach them.

9.4.1. Sample code

One of the first things that developers will seek out once they’ve learned what they want to do with your system, or even while they’re exploring, is sample code that lets them get started using the system right away. It’s important to provide an easy way for them to learn about the authentication system for your platform, but it’s equally important to give them some building blocks to start working directly with the system as quickly and efficiently as possible.

Authentication libraries

When a developer starts working with your system, the number one difficulty encountered is generally related to authentication and authorization. Providing supported libraries in as many programming libraries as possible is critical to making sure that clients written for your platform use the authentication mechanism in a reasonable way. Most authentication systems require knowledge of both encryption and the HTTP protocol. Cryptographic signing algorithms are complicated to create, and it’s easy to make mistakes when creating a signing library. Leaving this task to your developers, who aren’t likely experts in this field, creates unnecessary work for them, as well as a strong likelihood that there are some incorrect assumptions in their code.

When providing a signing library, you also need to include a great README file to help your developers implement the code—code guidance that makes it simple to integrate the code into their client. The Akamai platform has many signing libraries available in the GitHub repository that follow these guidelines at www.github.com/akamai-open.

Besides this requirement, it’s quite helpful to provide sample code for most, if not all, of the endpoints in your platform. The next section discusses how to create useful sample code and provide it in a form and location that’s useful for your customer developers.

Reference implementations and code samples

Working examples for the endpoints, workflows, and integration possibilities make it quick and easy for a developer to see how to interact with different endpoints. Even if you don’t have code for each endpoint, the more code you have available, the better. You can run reports on your API to see which APIs are called the most by your customers and be guided by that knowledge when making your sample code. Additionally, when meeting with or training your customers, be sure to make a note of the functions the customers are most excited about. Even if they’re asking for something a bit more complicated, providing sample code for that use case helps you serve that customer as well as other customers.

Great sample code does the following:

• Demonstrates one of the workflows you included in the documentation
• Avoids any tricky mapping or abstract functions
• Provides debugging output so that the user can see what the conversation between server and client includes
• Is consistent across all the examples in terms of error handling, debugging, and verbose output

An example of good sample code is found in the following listing, which is used by Akamai as part of the Getting Started tutorials. It includes the use of an authentication mechanism and an example set of calls to the diagnostic tools endpoint. The code itself does something simple—calling the standard network utility dig, but even this makes for a great Getting Started guide, as most engineers are familiar with this utility, so the only thing they’re focused on is the interaction with the system.

Listing 9.1. Basic API sample code

#! /usr/bin/env python
# Very basic script demonstrating diagnostic tools functionality
#
import requests, logging, json, sys
from http_calls import EdgeGridHttpCaller
from random import randint
from akamai.edgegrid import EdgeGridAuth
from config import EdgeGridConfig
import urllib
session = requests.Session()
debug = False
verbose = False
section_name = "default"

# If all parameters are set already, use them. Otherwise
# use the configuration from the ~/.edgerc file
config = EdgeGridConfig({},section_name)

# Allow for command line or configuration file inclusion
# of "verbose" and "debug"
if hasattr(config, "debug") and config.debug:
    debug = True

if hasattr(config, "verbose") and config.verbose:
    verbose = True

# Set the config options
# This is the standard method for all of our signing
# libraries in every language – set the authentication
# for a standard HTTP library using the client_token,
# client_secret and access_token
session.auth = EdgeGridAuth(
    client_token=config.client_token,
    client_secret=config.client_secret,
    access_token=config.access_token
)
if hasattr(config, 'headers'):
    session.headers.update(config.headers)

# Set the baseurl based on the 'host' information in the
# configuration file
baseurl = '%s://%s/' % ('https', config.host)
httpCaller = EdgeGridHttpCaller(session, debug,verbose, baseurl)

# Request locations that support the diagnostic-tools
print
print ("Requesting locations that support the diagnostic-tools API.
")

location_result = httpCaller.getResult('/diagnostic-tools/v1/locations')

# Choose the first location for the diagnostic_tools call
location = location_result['locations'][0]
print ("We will make our call from " + location + "
")

# Request the dig information for {OPEN} Developer Site
dig_parameters = { "hostname":"developer.akamai.com.", "location":location, "queryType":"A" }

dig_result = httpCaller.getResult("/diagnostic-tools/v1/dig",dig_parameters)

# Display the results from dig
print (dig_result['dig']['result'])

This example demonstrates several useful patterns. It’s clearly demonstrating a fairly simple workflow:

• Request the locations from the platform
• Select a location from the list
• Make a dig call using this location

Without sample code and a workflow example, developers were getting confused about where to get the location information in order to make the dig request. There are two requests to the system:

GET /diagnostic-tools/v1/locations
GET /diagnostic-tools/v1/dig?
hostname=developer.akamai.com&queryType=A&location=Schiphol%2C+Netherlands

In this case, the example shows how to make a call with and without extra parameters, in the code language being used.

Note that in the case of Akamai, we’ve created the diagnostic-tools script in six different languages, and we have a goal of including all the languages we have libraries for. The more examples you can provide that are meaningful to the most customers, the more success they’ll have without needing direct handholding from you.

9.4.2. Reference applications

Sample code is generally about a simple workflow—figuring out how to get specific information from an API endpoint. To create a meaningful application, many of these will need to be combined together. Providing a couple of sample applications that are more functional is a great way to help developers see how to work with complicated data from the API. If you check the GitHub repository for Akamai, you’ll find a few application examples using Node.js. In fact, one of the examples was documented in seven separate blog posts on the forum so that users could work through the example from start to finish and run it on their own system to browse through the information it provided.

9.4.3. Tools and techniques

An excellent teaching/guiding set of tools and techniques should be available to help your developers learn about the whole set of APIs provided by your team. As different people learn in different ways, so too do different people like to explore and understand topics in their own direction. Provide tools and techniques that help each user learn about your system in the way that makes the most sense to that individual.

Using API consoles to understand calls

Earlier, in section 9.3.1, I provided a short description of API consoles. For an example, take a look at figure 9.4, a screenshot of the Apigee console for the Twitter API. This is a great example of using a console to look inside a successful request to the API. I’ve set up the tool to use OAuth authentication, which represents synedra on twitter—hence, synedra-twitter. Any calls I make to the system will happen on behalf of this user. Below that section is an area where you can pick out which API you want to call using the console.

Figure 9.4. The Apigee console for exploring the Twitter API lists the most common endpoints in the Twitter API, making it easy to understand the breadth of information available via the platform. The authentication can be activated to use your Twitter identity, using OAuth, so that the API responses are exactly what you see when accessing Twitter directly.

As an example, I’ll select the /statuses/home_timeline.json option. Figure 9.5 shows the result of this query. The screenshot doesn’t show the response headers (although if you scroll up they’re there), nor does it show the entirety of a request. I encourage you to play with this console yourself at https://dev.twitter.com/rest/tools/console.

Figure 9.5. For the Twitter API, there are example calls for the majority of the Twitter endpoints. Selecting one of these demonstrates what the request and authentication look like, and how the response is formatted.

The Apigee console is available on its website. You can build your own Apigee-to-go console to embed in your developer documentation. A generic console is also offered at https://apigee.com/console/others.

Figure 9.6 demonstrates how the Apigee generic console can be used to access the Irresistible API. As you can see, if it’s a simple enough API, it’s easy to fit everything in one screenshot.

Figure 9.6. The Apigee generic console can be used to call the /toppings resource from irresistibleapis.com, making it possible to see all of the request and response information in an easy-to-read format. This enables you, or your users, to easily explore and understand the various endpoints.

A couple of other consoles available—in fact, all the schema modeling languages I discussed—make it simple to create mini-consoles for all the calls. The difference between a schema model–based example call and a console call is that the console is making the request directly to the API, whereas the schema model will only return exactly what appears in the document. Both are valuable, but it’s worth considering whether you should add the console to the toolboxes of your users in order to provide that extra dose of confidence live calls make. In addition, providing examples of successful calls can help developers debug their calls themselves, by showing what the exact request path, body, and headers should be to get the desired response.

Command-line utilities

Consoles are great, but the utility is pretty much bounded in the web page. It’s not possible to interact with the input/output without copying and pasting. If a developer can successfully make the call from the command line, it becomes much easier to grab the result and stick it in a file or process it with a local script. There are two main command-line utilities for making HTTP calls:

• curl—The curl command is the old standby. Most developers and system administrators are familiar with the curl command as a way to request web pages. It can, and does, get used to scrape web pages and is quite useful for grabbing HTML files in order to process them. But it’s not tuned for API use, and the output formatting makes it difficult to visually parse the response for a request to a JSON-formatted REST API call. Additionally, creating a custom authorization module is not straightforward, and so companies frequently “wrap” curl to include the authentication in the calls (which means the credentials are likely to be passed on the command line).
• HTTPie—HTTPie was recently written as a command-line alternative, and it’s strongly tied to API calls. JSON responses are formatted well, with color coding and indentation. Writing an authentication plug-in is relatively easy, and because of this several HTTPie authentication plug-ins are available. It’s open source, free, and definitely worth including in the documentation as an easy way to interact with the API from the command line.

Other tools

Several places in the book have pointed to different tools and techniques you might well want to share with your developers. Remember, the more information you provide to them about ways to interact with the system, the more likely they are to become engaged, productive members of your community.

• HTTP sniffers— These tools make it possible to watch the traffic as it flows to and from your personal device. They are great, but some of these tools (such as HTTPScoop) can only view HTTP traffic, which locks out any debugging of traffic. Those that do provide a proxy answer to sniffing HTTPS (Charles, Fiddler) are sometimes still not able to see the traffic if the API engine has been set up to disallow proxy calls.
• Code debugging— Teach your developers how to inject error handling and HTTP debugging into their code. All your code samples should support this by default. More information is almost always better, and it means that your developers will ask more meaningful questions.
• Building clients from schema models— Each of the schema modeling systems I’ve discussed have open source tools available to allow your developers to bootstrap a simple client so they can work from there to build exactly what they want. When you don’t have sample code for a particular endpoint, make it easy for your developers to leverage the base API design document to get where they’re going as easily as possible.

There’s no specific list of tools you should provide guides for or make available to your developers. Listen to your partner developers to understand where their pain points are in getting started, working with your simple APIs, or integrating your more complex APIs. Then find ways—even odd, unconventional ways—to help the developers succeed at what they’re trying to achieve.

9.5. Developer support

The final pillar of developer experience is developer support. As with the other pillars, I’m going to tell you that it’s critically important to the success of your API. It’s arguably the most important piece because your developers will only need help of this type when they’re stuck and frustrated. If you don’t provide excellent support, you can encounter various challenges:

• Developers could get frustrated and give up on using the API. They may come up with different, inefficient, or unsupported answers to their problems.
• Although slighting any facet of the developer experience can make developers grumpy, failing to respond to a specific blocker can create a great deal of loud, negative sentiment for your team among the developers.
• Taking the time to listen to the challenges that your users have can help you improve the experience for future developers by making answers excellent and making sure they’re findable within your portal.

In short, it’s extremely important to have a plan for how you’re going to actively support your developers before your API gets deployed.

Some companies have the resources to provide support around the clock—and APIs that need that level of attention. But most APIs, in particular when they start out, can get by on much less support. The better you’ve done with the earlier items in this chapter—with communication, documentation, and tools and techniques—the less support you’ll need to do.

What is important, though, is that your developers know what kind of turnaround they can expect for questions they ask. It’s best to try to get back to developers with questions within a business day. Your developer portal needs to be organized well so that the information they’re seeking is easy to find.

There are two different areas of support to consider. The first is interactive support, such as a forum, help desk, or email alias, where developers can ask specific questions and receive answers from your team. Based on the interactions you have, you can, over time, build up a noninteractive repository of blog or forum posts, or create a FAQ, to help future developers find the answers they need quickly.

9.5.1. Interactive

Interactive support is generally the mainstay of your developer support program. This is the system you implement in order to handle the questions from developers and the answers you provide.

Support models

You can use many different mechanisms to handle this type of support, and each has its advantages and disadvantages:

• Email alias— This is the most common support methodology that companies implement, and it’s a tempting proposition. It’s free, customers know how to use it, and it doesn’t take any time to set up. But an email support queue has several problems:
  • There’s no archive but individual email archives.
  • You aren’t building a knowledge base out of the interactions you have with your customers.
  • If someone leaves the company, all the interactions that person had will evaporate.
  • There’s no way to find similar questions/answers to add more appropriate assistance.
• Help desk application— This is a great option for many companies that want to give users a personalized feel while building up a knowledge base, but the system is somewhat closed to visitors and won’t necessarily help them find information that they need.
• Forum— This is the most time-intensive, but it creates a knowledge base as it goes along, so that customers and visitors can type a question into the search box and find appropriate previous threads. Additionally, this system supports posts with tutorials or overarching posts about the system, allowing you to cover frequently asked questions in a deliberate way.

Selecting the correct model for you will take time, and you may go through a few different options before you land on the one that works best for you.

Efficient interaction

As you run through different interactions, you’ll probably encounter many developers who don’t ask questions efficiently. It’s critical to set context when providing documentation, and it’s important for developers to give you the right context when they’re asking for help. The experience when the context isn’t set looks a lot like this:

• Q: This is broken. Help.
• A: What is broken?
• Q: The cookbook endpoint.
• A: What happened?
• Q: It didn’t return all the books.
• A: What were you doing at the time?
• Q: Trying to get a list of 1999 cookbooks.
• A: What did you expect to get?
• Q: A list of all of the 1999 and later cookbooks.
• A: That’s not how it works.

Okay, that’s a little drawn out, but I’ve seen so many conversations that go through these cycles, and seriously, there’s little that’s more frustrating for any human than having to keep iterating on a problem that’s not working. Teach your developers to ask questions well. If they don’t, give them the pattern so they get it on the second iteration. It looks like this:

• I did X.
• I expected Y to happen.
• To my dismay, Z happened instead.

You may argue that the second section isn’t needed, but trust me, it is. So many “broken” things are “broken expectations.” Note that this is still a bug in your product, but it’s a documentation bug. You set their expectations incorrectly. To illuminate the types of problems you might see, here’s an example:

• I jumped off a cliff.
• I expected to sprout wings and fly.
• To my dismay, I plunged to my death instead.

See there? It’s not a bug in gravity. The problem was with the expectation. If they’d said, “I jumped off a cliff and plunged to my death!” you’d be hard-pressed to understand why this was an unexpected result. Help your customers to give you good, complete questions so that you can answer their question and quell their frustration with one or two interactions instead of dragging both of you through the mud.

9.5.2. Noninteractive

As you answer questions that users have, you’ll likely experience clumps of questions related to particular issues, which is your signal that it’s time to create some noninteractive information. Yes, when a conversation happens in your forum (or other system), there’s an archive of that information, but sometimes you need to start at a higher level and walk people through the solution step by step. In those cases you’ll want to create static content so that when people search on a particular topic, they find a fully fleshed-out answer to the question.

Here are some examples of topics that I’ve written blog posts to clarify:

• Purge— Several different APIs at Akamai allow customers to purge the content from the edge (cache) systems. But how they interact, which one is current, and how to plan for the future is not at all clear. I wrote a post clarifying what a new integration should do and how.
• Tutorial— We created a set of seven blog posts within the forum system explaining how to create a sample application around one of our more complicated API systems.
• Context— We wrote a few different posts explaining how our system worked and what users should expect when working with it.

9.6. Summary

This chapter explored the following:

• Pillars of developer experience— You learned the essential factors for ensuring that your developers achieve success easily and quickly.
• Clear communication and a discussion of the various types of information to share with your developers— Consistent, clear, and transparent messages about your business value, metrics, and expected use cases are critical to creating a great developer experience.
• Documentation— Although reference documentation is vital, it’s not the only type of documentation needed for your API clients to thrive. Even more essential is information on what can be done with your API and tutorials to guide developers through the process of accomplishing those tasks.
• Building blocks— Developers respond enthusiastically to sample code and applications—examples to help them get started quickly and effectively. Additionally, libraries to abstract difficult tasks such as authentication can smooth out the trickier tasks on your platform.
• Support— Providing a consistent method of asking questions, finding answers, and learning new information about the system is equally important to the other pillars. Whichever method you choose, whether it be a forum, email, or some other mechanism, the most important piece of support is making sure that your customers understand where to get help and what kind of response time to expect.