You have a new public Application Programming Interface (API) that you want to help drive your business. Your going to need outside developers to use it such that it remains relevant; in other words, you need to sell them on using your API. If your lucky, the developers that come to your developer portal will go through an educational journey that will turn them into your API zealots. But is it really luck? I don’t think so; I think that it is about getting the right information to each developer at the right time during their journey. If you get it right, you will end up with a community of developers who help each other and thus help you reach your goal of becoming the coolest API on the planet; if you miss the mark, you and your API sink into irrelevancy.

Let’s start by coming up with names for the phases that a developer will go through as they learn to become expert about your API.

  1. The Candidate Developer – The candidate developer is not your developer, at least not yet. You’re going to have to earn them. When the candidate developer comes to your portal, she is in discovery mode. She is trying to understand what value (if any) that your API can provides specifically to her. You need to remember that a developer only wants one thing from you – help to do their job better and/or faster. What the candidate developer wants from you is an quick-to-understand overview of what your API does such that they can decide if your API warrants any additional investment of their time.[1] Your goal with the candidate developer is simple, get them to spend the time to learn your API.
  2. The Student Developer – The student developer has decided that your API sounds pretty good and it is of use to them. But they don’t yet understand how to use the API and thus they don’t yet know how to extract the value from it. What the Student developer is looking for is answers to some pretty basic questions. What do I need to do to get started? How do I use the basic API? How do I build my first Hello World application? Answer these questions and you’re off to a good start in getting a valuable developer to join your developer community.
  3. The Intern Developer – The Intern developer is well along the journey. They have already made a pretty large commitment to learning your API. But they still have a lot to learn. They know the basics but they don’t know how to build something useful and you have to help them with that. Specifically, they are looking for Tutorials, Use Cases, Sample Code, and Support Forums to get help when they get stuck. They are looking to use your API to build something useful. They are doing real work but they are still learning. Your goal is to help them to become experts on your API through doing real work.
  4. The Expert Developer – Expert developers are pure gold. They might know your API as well or better than your own API authors. They use it day in and day out. They are very valuable members of your developer community because they will help your Intern Developers on their journey to become new experts. They’ll do this by jumping into your forums and providing answers to those tough questions that only an expert can provide. But Experts still need things, in particular, they need to network with your API Authors, other Experts, and they need detailed reference information about the API. Things that you need to provide for the Experts are detailed API Reference Manuals, source code, recognition of their expertise, and networking opportunities. Oh, one last thing, the experts are also the ones who will tell you how to improve your API – make sure that you listen to them because they know what they are talking about; they are experts after all.

Thus the Developer Journey is a learning curve that looks like the graph below.

You will have four different developer segments to cater to. You know basically what they want but to scale your portal needs to cater to these needs in a way that your developers are catered for. Your portal should be adaptive in that it understands each developer who is on the portal, where they are in their journey, and the portal needs to adapt to these needs offering them what they need when they need it.

Your portal might start by offering a Candidate an overview but you should never make that mistake with an expert – you’ll offend. Instead, over time you need to cater the portal to anticipate the needs of the developer.

One of the things that we recommend to do with an API Portal home page is to provide what we can a 1-2-3; a three step call to action. The 1-2-3 are the three next things that you should do to move forward along your developer journey. For example, when you first go to the portal home page as a Candidate the 1-2-3 might be:

  1. Watch the Overview Video
  2. Learn How Others Are Using the API
  3. Read the Getting Started

But after I’ve done these first three, it should adapt and now offer a new 1-2-3 which has become the 4-5-6[2]:

  1. Walk Through the Hello World Example
  2. Read the Tutorial
  3. See the Use Case Samples

Eventually offering a 7-8-9:

  1. Start with Sample Code
  2. Get Help on the Forums
  3. Access the API Reference Manuals

And finishing with a 10-11-12:

  1. View the Source Code
  2. Network with Our Experts
  3. Tell us How to Improve

You can see how the portal can be made to adapt to the needs of each journey of each of the developers prompting them along the way you just need to understand each of your developers and where they are along their journey.

The illustration below shows how you might modify the 1-2-3 call to action as each developer gains more skill. You will no longer ask one of your developers to do something that they’ve already completed and that is no longer relevant in that developer’s personal journey to becoming expert. Rather, your portal now encourages each developer to reach the next step, by asking them to complete the next call to action. You’re delivering the right information to your developers at the right time.

You win in that you have a well balanced and growing developer community. You have the expert developers who are helping you improve your products and services while they are also helping newer developers also become experts. You have a nice balance of newer developers coming in to the community, becoming sold on your API and doing something useful with it. In short, your API become relevant because it is used and loved by developers.

It's all about getting the right information to each developer at the right time.



[1] NOTE: You’ve probably heard that developers don’t want to be marketed to. Well, none of us want to be marketed to. But it is not marketing if you are giving me the content or information that I need. I know, technically it is marketing but it relevant marketing and that is the difference.

[2] NOTE: Your three call to actions would actually be more granular than illustrated above. For example, if I had completed items 1, 2, and 4 then the next three call to actions would be 3, 5, and 6. By knowing what call to actions a given user had completed, you have an idea of where they are on their journey to expert and you should adapt your home page to suit each developer’s specific needs.