In the previous parts of this blog series, we covered benefits of APIs, API strategy, business models, API design, operations, and marketing.

Developer experience (DX) is about more than having a well designed API – it’s the packaging and delivery of the API, which are key to ensuring it gets adopted by developers. Pamela Fox has said:

Developer experience is the sum of all interactions and events, both positive and negative, between a developer and a library, tool, or API.

Your API might be wonderfully designed with simplicity and flexibility, but if it’s hard to sign up for and test, developers won’t have a good experience. They won’t engage with or adopt your API and your efforts will be wasted. On the other hand, well thought out API design has a considerable impact on developer experience and adoption, so the two go hand-in-hand.

John Musser provides a great take on what it means to get developer engagement in his OSCON 2012 talk, What Makes a Great Open API?:

  • Making it very clear what the API does
  • Providing instant signup
  • Providing free access
  • Being transparent about pricing
  • Having great documentation

“Time to first hello world” (TTFHW) is a key metric to improve API design for easy adoption. It’s a great way to put yourself in the shoes of a developer, and should be the main driver for improving the DX of your API. TTFHW should cover the whole developer engagement process, so you can optimize it to be as quick and convenient as possible. It’s important for developers to have a good experience from the start because these first impressions will build confidence that your API is well organized and things are likely to work as expected. If the “hello world” moment of success takes too long, you risk losing developers.

Creating a Developer Program

Elements of a Developer Program -- 3scale
Every API program needs to have a developer program, regardless of whether you expose your APIs publicly, to partners only, or only internally. And every developer program should include the following elements in some shape or form:

  1. Developer portal
  2. Community building
  3. Evangelists
  4. Events
  5. Communications and social media
  6. Pilot partners and case studies
  7. Acceleration via ecosystem partners
  8. Measuring

Developer Portal

The developer portal is a key element of a developer program. It’s the main entry point for developers to sign up, access, and use your APIs. Getting access to your API should be dead simple and frictionless for developers, so they can get started quickly. Again, TTFHW is the best metric to measure this and may include streamlining the signup process – the simpler and quicker, the better. We recommend that developers be able to invoke your APIs to examine their behavior (requests and responses) without any signup at all. Interactive API documentation based on industry standards like Swagger, such as that offered by 3scale API Management Platform, is a great way to achieve this. Also, supplementary content such as getting started guides, API reference documentation, or source code help to reduce the learning curve.

Community Building

Community building includes your physical and virtual presence. Where and how you appear in both aspects depends on which developer personas you want to address. Your physical presence might include events, which are a great opportunity to get the word out about your API program, to promote its benefits, and to increase adoption. It’s also valuable to get in touch with the community of developers using your API and to meet some of them face-to-face. Relevant events may include large developer conferences, developer days, bootcamps, hackathons, workshops, or trainings.

Developer Evangelists

The role of a developer evangelist is fairly new. There are several resources on the Web which describe this role in more detail. Next to the developer portal, an evangelist is one of the most important element of a successful developer program. My onion model of developer evangelists summarizes some of their most important types of activities. This model is also scalable, as it can be applied to a one-man-band evangelist or a team of evangelists.

Pilot Partners and Case Studies

Pilot partners are usually early adopters who you work with closely. There are two main advantages: First, you get early feedback about your API and you can improve it accordingly. Second, if the pilot works out nicely, it can be used as a successful case study for general promotion and marketing activities. It also shows that your technology works and gives inspiring examples of what it’s possible to do with it.

Acceleration via Ecosystem Partners

As an API provider, you are operating in an ecosystem of partner and vendors. These partners often have their own means and networks of content distribution and communication. We recommend identifying alliances, that can be effective in helping to increase the adoption of your API. Often such alliances can be found when APIs are complementary and provide value to developers when combined.


Only what’s measured can be managed. Measurement is an important element of a developer program in terms of understanding its effectiveness and figuring out what aspects should be improved and how the developer program could better contribute to the objectives of the API program. Metrics for the developer portal might include page visits, signups, API traffic, or support requests. Events can be measured by the number of attendees who were exposed to your API, the number of leads collected, or (especially at hackathons) the number of API signups. Once you have metrics in place, you can examine correlations such as “did a talk at an event trigger more API signups?” Swift provided an insightful presentation about the Nuts and Bolts of Developer events.

Example: The Context.IO API

At Context.IO you hear the term “developer experience” in conversations on a daily basis because it’s part of every decision made. Context.IO is constantly thinking of ways to improve the experience for customers – and it can always be better.

The biggest hurdle for the company has been at the very beginning; getting developers to understand the value and wide range of use cases for Context’s API. Context.IO takes the complexity out of connecting to email servers and enables developers to easily build apps on top of their users’ email data. If a developer has ever tried to work with IMAP or Exchange, they understand the value almost immediately. It may take a bit longer for others, in which case Context.IO usually runs through a handful of app examples until the “lightbulb moment” appears.

Another early step is prompting the developer to connect an email account they control via Context.IO’s interactive console, which reduces TTFHW to seconds. The client can make requests against their own email account and see responses without setting up a dev environment or writing any code. The console on the Context.IO website is a great way for developers to rapidly consider options, and learn what Context.IO can do. Client libraries are easily available on GitHub when it’s time to dive into writing code.

After a developer has had a chance to try out the API, someone from the Context.IO Evangelism team follows up with each and every one of the new users to make sure they don’t have any outstanding questions or problems. While this “high touch” approach has scaling issues and may not be practical depending on many companies’ new customer volume, Context.IO has gotten an incredible amount of value out of these efforts. New API users have the best feedback on how to improve onboarding. Not only do those early conversations help improve resources, but a conversation can smooth over any issues early users may experience.

As developers become more familiar with the API, an often-seen occurrence is for them to think up new and unique ways to use Context.IO. Email as a data source has limitless use cases, so it’s useful when something new is revealed. Documentation is usually complete enough for developers to get started, but if something is missing or Context.IO doesn’t have the answer, the company works collaboratively with the developer to figure it out.

Overall, it’s fair to say Context.IO has a pretty “high touch” approach to developer experience. It’s absolutely more work, time, and money than other approaches. But at the end of the day, the great results and the information collected are invaluable.


  • Understand who your developers are and how to address them. Try coming up with an elevator pitch about your API’s value.
  • Define, measure and constantly improve your TTFHW metric.
  • Make sure that your onboarding process is as painless for developers as possible to lower the barrier of entry, including having some level of access even without signing up.
  • Keep in mind that leaving enough on the table for developers to be successful will eventually make your API successful.
  • Provide adequate support to make developers feel taken care of. A lot can be covered via self-service docs and forums, but you should provide other channels too for questions that are more in-depth.

In the final installment of this series we will summarize the key success factors of effective API programs.