API Model Canvas: Developer Experience is a Key Ingredient of Quality APIs

Dx-is-key-part-of-quality-APIsAccording to The State of API Survey Report 2016 by Smartbear, nearly 85% of the respondents agree that API quality is crucial to their organization. The same survey identifies the top three reasons keeping organizations from delivering quality APIs are:

1) Increased demands for speed
2) Lack of integration between tools and systems
3) Managing expectations of different stakeholders

A remedy for the first reason can be found by fine-tuning architecture and optimizing code. The second reason requires a DevOps approach to operations and automated solutions, which in an API-centric point of view can be labeled as APIOps. The third reason is a bit more tricky and is discussed in this post. Part of the solution is to utilize the still rather fresh idea of the API Model Canvas.

API Model Canvas – offspring of Lean Canvas

The API Model Canvas should be familiar to startup people since it resembles Lean Canvas. The Lean Canvas proposed by Ash Maurya is an approach for entrepreneurs and startup businesses that is more problem-focused than its ancestor Business Model Canvas. Canvas models take customer needs into consideration, force business design to be iterative, and unlock fast, adaptive building methods.

At first sight these methodologies might look pretty similar. API Model Canvas is, as name suggests, more focused on the API economy and for situations where the API is a product. What differentiates API Model Canvas from its ancestors is the focus on developers, the rockstars of the API economy.

Developers are the Rockstars of the API Economy


Developer experience is a concept referenced in the API world very often, and for a good reason. Developer consumers are the lifeblood of the API based economy. The API Model Canvas reflects this importance with three sections dedicated toward keeping them in the spotlight: Developer Relations, Developer Program, and Developer Segmentation.

Developer Relations

As Phillipp Schöne of Axway sees it, API providers must go beyond great API design and documentation, and work toward creating superior end-to-end experiences:

“If you are in a competitive situation it can become a differentiator to have a good and well thought out experience, even if the price is a little bit higher. When API providers consider Developer Experience, often only API Design is taken into account, which is wrong.”

Running an API with quality developer relations means intimately knowing your consumer, their needs, and advocating on their behalf. For active community participation, Phillipp sees hackathons as a “great way to learn what external people think about your offering… start with smaller groups and go bigger if you get more confident with your offering.”

Developer Program

Maintaining DX means having a holistic product approach to APIs; part of this means forming an internal product team, with the responsibility of API program upkeep and marketing. Tuning into consumer feedback is important, but Phillipp also believes that “if providers ‘eat their own dogfood’ they usually experience the caveats and hurdles of their offering quite fast.”

Developer Segmentation, Targeting and Positioning

We’ve seen how the developer consumer market has diversified in recent years. As with any product, the right segmentation needs to be considered. This involves an intimate understanding of your consumer and where they fit within the API economy. How you target specific developers depends on the market and audience:

“For example, if you try to create something specific for a vertical or niche try to leverage industry specific forums, websites, and events to promote the idea. If you target a broader audience it’s more complicated and you have to search for developers who feel the most pain and gain and would benefit the most from your service.”

Schöne adds that quickly compiling customer references and testimonials is paramount for establishing a reputable image.

Addressing the Entire API Model Canvas

The API Model Canvas is easy to follow and fill in. Having succinct answers for each section can help you nail down your value propositions and specific strategies. You should not do it alone or fill everything in like writing an essay, rather, it should be designed as a team.
More importantly — do not design an API business model alone in the office cubicle. You should involve IT people, business strategy people, and a few developers from candidate customers. Because your API is expected to bring value to these customers, the foremost aim should be to solve their problem and solve it well.

Blog-Post-Wide-CTA-API-StackCase Study: National Library of Finland

Use of the API Model Canvas has been a proven asset across several teams. One of the latest teams to use it was the The National Library of Finland. They have millions of data objects about Finnish journals and newspapers dating back to the 17th century. All this information needed to be made accessible in a way that current newspaper publishers, researchers, and citizens could efficiently consume. In brief, they needed a quality API.

The project was a three step process, with the API Model Canvas used in the second phase:

  • Define an API strategy. Obviously strategy emerges from the organization, which in this case was National Library of Finland.
  • Utilize API Model Canvas to craft a business model for APIs needed.
  • Describe API with design driven language such as RAML or Swagger.

Of course after design is finished and tested with a mockup server, the API must also be implemented. For this project, we decided that we would leave implementation out at this stage and focus on business model and API design.

MVP for next step

During the first APIOps camp, we did not go through all boxes in the API Model Canvas. Instead we took a lean startup approach and started from the middle at “Strategy for the API and Objectives”. After that we jumped around the boxes to gather a Minimum Viable Product (MVP) for the next step. This was possible since we had experience in Lean Startup style development and canvas models. For example, we did not touch “Cost Structure”, “Developer Program”, or “Developer Relations” at this point.

The idea was to collect just enough information for the next iteration of the API’s Swagger description and not to plan anything unnecessary. In the process, two collections were identified from data and feedback gathered from data consumers: newspapers and journals. Based on that we decided to define read interfaces for both with similar structure. In practice we defined newspaper endpoints first and then cloned the structure in Swagger design. We did not touch write interfaces at all, since we narrowed down the scope to just API consumers and excluded data administrators.

After adding some basic endpoints to the API, we collected feedback from developers who we had engaged with earlier. Including API consumers in the API design phase gave us insights on what developers were looking for in the documentation, and shed insight on what keywords and writing style grabbed their attention. It also convinced The Library of Finland to dig deeper into DX than just providing nice documentation: code examples for utilizing API, case descriptions, and providing customer support. In other words, the client understood the need and value of a proper developer portal.

This cycle goes back and forth: filling in and altering the API Model Canvas, returning to Swagger design and developer testing. After some rounds, you’ll have a solid business plan, and golden API Design loved by developers. At that point you are ready to implement it.

Gain speed and make it fun

API Model Canvas is an important tool and in this particular case worked very well. For a team with a startup mindset and familiarity with Lean Canvas, getting started is easy going. At the end of the day, API Model canvas can make business model design fun — even people participating in this type of process for the first time will see API Model Canvas as a solid tool for API centric business design.

Incorporating third party developers into the modeling process right from the start eliminates the risk of losing your Developer Experience focus. Keep in mind that developers are the people through which you’ll reach business agreements and convince upper tier managers. If developers hate your API, you’ll lose revenue— every developer lost is revenue lost.

Final Thoughts

There are many theories on API business modeling; the Nordic APIs philosophy of practice, for example, involves 6 core tenets. Whether following these Insights, the API Model Canvas, or other toolkits, Phillipp notes that the “true importance is that the API Provider starts thinking about the different dimensions and implications of their API.” For him, the main traits a lean API MVP design must consider are:

  • Product ideation and preparation
  • Monetization and growth projections
  • Legal aspects: are there any legal obligations or regulatory mandates we need to worry about?
  • Infrastructure Questions: how to connect to existing Data sources, how do we manage API consumers, how do we want to scale, how to we monitor our SLA and service quality?
  • Security Questions: do we need security measures like rate limiting and other protection mechanisms and how do we enforce them?
  • Backoffice Questions: how do we bill our consumers?
  • Marketing Questions: how do we promote our product and how can we drive adoption?

Lists like these go on and can easily be extended. Modeling a business around an API may seem daunting, but the process is really similar to building out other software or products. Many areas require continuous improvement, which is why the APIOps strategy is so helpful, as development and running services can be based on or automated with APIs entirely.

For more on DX, DevOps, and API strategy, come to our API Stack Conference which will feature talks by Jarkko Moilanen, Phillipp Schöne, and other API experts!