Designing great API developer experiences – Part 3

Designing a great experience for API developers is only possible if you understand who the developers are and what tasks they are trying to perform.

Matthias Biehl Matthias Biehl

Designing a great experience for API developers is only possible if you truly understand who the developers are and what tasks they are trying to perform.

There are several aspects to a great developer experience (DX): In Part 1, I talked about how the functional aspects of APIs must be accompanied by this great experience. In Part 2, I talked about how API consumers should be treated as a new customer segment and how it requires its own customer experience.

Here, I will provide some pointers on how to actually and practically do that and create an optimal experience for API developers. 

Who is the developer?

The developers using your APIs are diverse group. Get to know them by making surveys or simply talking to them. You will quickly discover that they have different views, but that you can cluster and segment them. There are the tech-oriented developers, there are business-minded developers, there are DevOps.

Create a list of developer profiles by listing the tasks the developers need to do, their motivation, things that would help them do their tasks and things that would concern or annoy them.

When it comes to defining the tasks of a developer, it is tempting to take a short cut and just say: “Developers write code.” But, according to research, developers actually spend only a third of their time writing code.

And how do they spend the rest of their time? They spend 23% in meetings, 19% with maintenance, 12% testing, 4% on   security issues and the remainder on other tasks. Developer experience needs to support all these activities as well as writing code …

  • How can you provide developers with information about your API, so they can better explain what the API does in meetings with their colleagues?
  • How can you help developers maintain their code that calls your API?
  • How can you help developers test their code that calls your API?
  • How can you help developers build secure applications when they use your API?

What does the developer try to do?

Sketching the customer journey is a widely used approach in user experience (UX) design and ensures that all steps important for the customer are covered by a mobile app or other digital solution. Let’s apply it to DX design: A developer journey is the sequence of steps that a particular developer persona goes through when trying to accomplish a task. Each developer profile typically has a different customer journey and typically each persona has more than one customer journey.

A business-minded role will have a different journey than a technical role. A technical developer role will have an onboarding journey and a journey around actually developing with the API.

Developer journey of a technical developer

The picture shows a typical, plain-vanilla journey of a developer who attempts to use your APIs. It includes:

  • Searching & finding the API needed for an ongoing app development task
  • Quickly assessing what the API does and whether the API is a match
  • Trying out the API on the developer portal
  • Signing up for sandbox credentials
  • Checking out some more detailed example code provided on the portal
  • Developing code of an app that uses the API: Hopefully the developer is able to use the API intuitively, but might also check documentation from time to time
  • Getting API security to work, one of the major stumbling blocks for developers, regarding OAuth and Scopes
  • Getting access to the APIs on the production environment
  • Checking API metrics, to ensure the app interacts correctly with the API
  • Getting updates on changes and issues for the APIs.

The developer journey for your APIs may differ – it all depends on the needs of your developer persona.

To conclude:

  • Find out who the developers using your API are
  • Learn what tasks they need to do
  • See what developer journey they go through
  • Decide what developer experience can best support them.

In the next part of the series, you will learn how to leverage technology for realizing and operationalizing developer experiences. 

Want to dive deeper into the topic? Check out the video on creating great developer experiences.