Developer experience in API Economy.Developer experience as well as flow state discussed are mental states and constructs. Developer experience is not about your API, it’s about the developer - consumer of your API. Great developer experience is immersive, you get sucked into it. Optimal onboarding to your API is a flow and that flow continues to first positive and enjoyable first success with your API. From there you find easy path to go deeper in discovering the possibilities offered in the API. Taking API into use feels natural and it rewards you for your efforts. Most importantly, it solves your problem. Top 1% of API industry manages to combine product-ceentric, customer-centric and developer-centric approaches.




Ying and Yang

It’s essential to understand that developer experience is two folded concept - internal and external developer experience. This dualistic nature of developer experience can be compared to Ying and Yang. Yin and yang are semantically complex words, the two are opposites of each other, but at the same time interconnected and interdependent. The same complex relationship applies to developer experience as well.

Internal developer experience is focused on the API developers and their processes and tools as well as documentation. Companies want to streamline API development processes with automation and lean practices (DevOps). Sometimes the internal and optimal developer experience and external customer experience do not match. Your architecture might cause some limitations or force you to select tools that are perfect for internal use, but without exra work do not fit into the world of extermal API consumers. The same dualistic nature of developer experience is also present in API design as one API Designer describes:

A good API designer would put [themselves] in the shoes of [another] person who is actually going to use the API whereas a good software designer would basically look at it from [their own] perspective if the design is good or whether the design is scalable”Design Practices and Challenges for Creating Usable APIs.

The clash can be sometimes avoided partially by “eating own dogfood”. The phrase suggests that some of the API consumers should also be your internal developers. If your internal API consumers are not happy with the developer experience, how could the 3rd party developer be? Optimal situation is that both internal and external developer experience are fully aligned, but it’s not always possible.

Some examples

I’m getting tired of bringing up the same company, but Stripe, which is known among application developers as the DX innovator of API Economy emphasizes the signifigance of developer experience:

At Stripe we consider this developer experience to be central to the overall experience of our customers.

The sentence contains notion of customer experience to be build around developer eXperience. This can also be seen as implication for developer-first approach in which application developer is the core strategy in product development.

Stripe was the company which introduced the famous 3-column API documentation to the masses and raised the bar for others. Now they have innovated again on that front. Their API documentation has gone through as metamorphosis again. The documentation is not API endpoint centric listing things you can do with it. Instead it’s feature or value proposition centric. In the docs you first find item / operation you want to know more. Then you are given details and list of endpoints with which you can achive the aim. From the list you get to details of that selected endpoint.

Stripe not only provides great API documentation, but also provides excellent libraries which enable simple operations with around 6 lines of code. They have understood that it’s their tasks to remove the complexity of the operation. The simplicity is what still amazes me. There has been a lot of thinking behind this to get this far. Nowadays you can find library driven examples for plethora of languages in their API Docs.

At Platform of Trust we have also planned to create libraries on top of our APIs to streamline the developer experience. We figured it out that first we need APIs (API-first), then supporting UX (developer portal) and after that library experience. With APIs and UX we first learn and develop the platform capabilities. Once the maturity is good enough we can start building libraries and encourage community to expand it even further just like Stripe does.

Developer-first is also principles of DocuSign. DocuSign did not start with developer-first product development strategy. After successful start they noticed that competition is getting tougher and similar solutions are nibbling their revenue and gaining customers. Something had to be done. They chose developer-first strategy and focus on developer experience first. In other words, DocuSign saw great developer experience as competetive advantage and developers as primary target group, whose hearts they needed to win.

Remember the business decision-makers as well

Does Developer-first mean that all “others” are unimportant? No, it does not. Application developers hardly ever work in isolation or alone. Other customers for your APIs are decision makers evaluating your API over competition and integrators attempting to debug a specific issue in an existing client. The latter and application developer are close to each other, but have different needs due to their role and context. Decision-makers are interested about features which are attached to customer experience layer of the onion shown above.

Some might claim that managers do the choice for the developers. That might be right, but even in those cases, developer experience matters. Keep in mind that your application developers might be working mith multiple APIs while building your dream application. Poor developer experience with APIs makes it harder to create apps. In other words your time to market increases and that most likely causes loss of reveneu. Your developers hate to work with APIs if they need to use their precious time to seek documentation, ask questions from the vendor or debug wicked errors which might be because of the API. Satisfied team builds dream apps. Unless you are forced to select APIs with poor developer experience, try to listen to your developers for choices.

Some more to read from 100 Days DX