Most of the time when we talk about developer experience, we mean downstream DX, the experience of developers that implement APIs. But what about the developers that create APIs?
In a previous post we wrote about the 8 stakeholders of developer portals, we argued that while the developers that use APIs are important, we shouldn’t forget about the experience of other stakeholders of a developer portal. In this post I’ll explore the experience of one of these audiences - the API developers - and explain what upstream DX is, when it matters, and how you can use a developer portal to improve it.
Gamifying digital transformation initiatives
Most organizations never consciously address the experience of the developers that create APIs, upstream DX. This is only logical, upstream DX doesn’t always need attention: a team that is dedicated to APIs will overcome friction on its own terms. In large enterprise organizations, however, where API development might be a secondary priority of a team, upstream DX can make the difference between a failed and a successful digital transformation initiative.
A few months ago while I was talking with an enterprise architect about the developer portal he was planning, I realized how different his requirements were from the more traditional outward facing API initiatives that we build most of our portals for. In his company the API initiative was a change project. He needed to convince people about the importance of APIs, explain how it is best to create them, and set out an evaluation process that could help his company to measure the progress in different business units.
We started talking about a workflow tool that would make it easy for employees from all over the organization to submit potential API resources before the actual APIs are built. Developers could then be guided through a set of consecutive steps that help them to develop quality APIs. I explained how a dashboard with an overview of the submitted resources, with a rating that indicates the progress status along a series of workflow steps, would then allow managers to monitor and compare progress between business units.
I believe that such a workflow tool, combined with a well defined process, can reduce the friction of a change initiative. Instead of trying to do everything at once, the most valuable resources can be turned into APIs through a step-by-step process with clear and tangible tasks. Instead of a dedicated API team, the API initiative can become a distributed process that uses feedback from your developer community. A conversation between API creators and consumers prioritises the development of APIs for the most important resources. Gamification (e.g. a dashboard with a 5-star rating), transparency and simplification can be used to increase the likelihood of success of a distributed effort to build quality APIs.
If your objective is to transform your business, and to make APIs an integral part of how your organization works (the way Amazon transformed its business), then you need to distribute API ownership throughout your organization. A central API team is great to prove the business value of APIs, but if you build APIs as a one off project instead of a continuously developed product, your APIs will soon fall in disrepair.
That is why I think central API teams should transition from an “API pilot team modus” to an expertise center that supports developers throughout the organization. Sharing scarce skill sets like API documentation expertise and developer experience best practices. I think this is the best way to transition an organization into the API-first mindset, necessary to capture the value of internal agility.
Upstream DX: the hidden developer journey
But what are the steps that need to be made to design an API, and how can we remove friction from the process?
1. Engage
Digital transformation initiatives in enterprise organisations often meet inertia or outright resistance. Employees might not have the time or appetite to participate in yet another change program of which they don’t understand the value. That is why a digital transformation program will first need to convince developers about the value of web APIs to be successful. The first job of an internal developer portal is to become an education and engagement tool.
- How can you convince people to put their efforts into an API program?
- How can you engage developers?
- Can you implement a reward model, or gamification system that will help them to prioritise the initiative?
2. Catalog
In large organizations it can be hard to discover reusable assets from different business units. This creates waste: different teams in the same organization might implement parallel solutions for similar problems. This is one of the most important reasons why many businesses start an API program, they want to create standardized interfaces between their departments and thus prevent the creation of one-off integrations. These standard interfaces can then later evolve into assets that are valuable in their own right, to facilitate innovation or to build new products.
- How do business units interact, can they be incentivized to interact through APIs?
- Do you already have a catalogue of digital assets and services that could be turned into APIs?
3. Design
API specification languages like Open API/Swagger, RAML, and API Blueprint make it possible to create a “contract” before an API is implemented. This is a best practice, as it makes sure that an API will meet the requirements of both the API providers and consumers. A developer portal could make it easier for API producers to communicate with the consumers of their APIs. Once announced, potential customers could express their interest in an API resource. The resulting dialogue between the API producers and consumers can then help prioritize what APIs get implemented first.
- Does your organization have an API design guide?
- Can you formalize a design process that involves both API creators and consumers?
- Do you already have communication tools that can be used to facilitate the design discussions?
4. Implement
While it is often straightforward to create a web API, it can be a lot of work to implement all the features needed for a mature API. Metrics, scalability, and especially security can add a lot of complexity to an API program. API management gateways solve these problems, and keep on innovating on the API management layer (e.g. Apigee’s machine learning solution Apigee Sense that helps API teams recognize security threats).
Remove as much friction as possible from the implementation process. Ideally an organization will provide an API management layer, so that API developers don’t need to address these individually. A central team can provide resources, tools and experts that can help accelerate the API development process.
- Provide tools to develop APIs.
- Make it easy to submit and update API documentation (e.g. through an integration with your code repository).
- Add documentation that explains best practices.
5. QA and Publish
Developer portals can play a role in the API quality assurance and publication process as a workflow and governance tool that you can use to define standards and implement control mechanisms.
In large organizations gamification features on a developer portal could provide an objective and transparent metric for API quality.
- Award quality indicators for each step completed towards a desired outcome (e.g. you get your 5th star when the onboarding documentation for X commonly used platforms is available on the developer portal).
- Create a “dashboard” for the organization that gives management insight into the health of the API program in their division and across the organization.
6. Feedback and support
As a final step it is important to give developers feedback about the importance of their work. Metrics should be available in the developer portal, with dashboards about the usage of individual APIs. Notifications about milestones in the usage of API resources can help to keep developers engaged in the API initiative. Bringing them back to the developer portal to invest additional time in improvements of their most used APIs. A centralized support team can act as a first line of defense that solves the most common problems, so that API customers don’t need to disturb the developers of an API.
- How will you measure API usage?
- What is your support plan?
- How will you keep developers engaged?
Conclusion
A small API team doesn’t need to worry too much about their upstream DX. That is why API teams tend to forget about the upstream developer journey: they are already familiar with the API development workflow and have less need for tools or interfaces that facilitate the process. But in larger companies (e.g. if your business has business units or other types of information silos), improvements in the upstream developer journey can help drive engagement and adoption.
Developer Portal: Strategy Series, Part 1 Through this series of posts we aim to provide you with strategies for raising the standards of both internal or external developer portals.
