I’ve said it couple of times in the series, but APIs should not be build just because. Companies do not do it too often since waste of resources is waste of money. Public sector in Finland is building APIs (have been doing for years already) but the reason why and for who the APIs are build seems not to be the driver. I kind of understand that and now that the government is forced to provide machine-readable access to data, they are going to build even more APIs.

Again the question is how to get started? Jumping into implementation or even in design process is not the way to get started. This applies to private and public sector alike. You need to know what is the purpose of the API. This is also where developer experience begins to build. It’s not something that is added afterwardds, but it’s there from day one. Or at least it should be.

Use canvas to find out pains and gains

No need to invent the wheel again in hundreds of offices. Use what has been offered for free and has been battle tested with plethora of APIs. Take a look at the APIOps Cycles method. I was involved in building the methodology. I coined the term APIOps 2015 from DevOps (Wikipedia).

In 2015 year, I also kickstarted APIOps community together with a few other enthusiasts. In the beginning, the idea of APIOps was formulated to stand for: APIOps goal is to design, build, test and release APIs more rapidly, frequently and reliably. Later with help of Marjukka Niinioja business aspects were injected to the thinking and soon after that APIOps Cycles methodology was born.

One of the tools in APIOps Cycles is The API value proposition canvas.

Section A: Tasks

What does the potential API consuming application need to do? Fill in a workflow of tasks when there is no API. Note that here the idea is that there is no API. Of course you can use the canvas to enhance and iterate your existing API as well.

Section B: Gains

What kind of benefits would API bring? Does it make any sense to build an API? Could the need be fulfilled with something else instead?

Look at the task list you defined earlier. Analyze what are the benefits of using an API to do the tasks. Think from the API Consuming application team’s perspective. What don’t they need to do themselves (assuming they even could do it)? What kind of painful tasks you could take away by providing an API? If you can’t find anything, then drop your gloves and seek opportunities elsewhere. Don’t waste your resources to battles you can’t win.

Section C: Pains- problems using API

Why would the team use the API? What problems do they see? API is not a bliss. It takes efforts to onboard, learn it, and maintain code built against it. These items are to solve to build great developer experience. Examples of problems:

Section D: Gain enabling features of the API

Match the expected gains with the gain enabling features of the API. Describe how you would fulfill the needs. How your API makes the developer’s life easier.

Section E: Pain relieving features of the API (DX)

Match the expected pains with the pain-relieving features and resources. Again, this where the traditionally understood DX comes into play. Great API documentation, freemium plan to learn and test, getting started guides, simple and easy to understand self-service onboarding….

Section F: APIs and Services offering the gain enabling and pain-relieving features

List the APIs and other services required to fulfil the feature list. This is a step I would not use too much time before testing the design with actual or prospect customers. If you have come this far with other sections filled, you probably have a prospect API. But you have not verified it yet.

I would not waste any time on thinking the backend before I know that it is wanted and needed and that the customers would indeed fall in love with it. Thus I would at this stage let the API designer to make the design and put it out as mockup API for customers to test before going any further. You’ll learn soon if the customers really want to it and did you get the pains and gains right. That’s how for example we at Platform of Trust develop new APIs.

Once you have verified the need and endpoints with parameters, you should identify the solutions for below items among other things:


Some more to read from 100 Days DX