The API Resilience Podcast explores topics that include mapping complexity and change in order to benefit the most from API programs. When we look at a commercial organization as its own ecosystem within a larger system—what do we need to be able to successfully and sustainably implant new tools?
This article discusses:
- How to build a successful API program using social practice theory
- The Tool Utopia Trap for DevPortals
- The People who make up Mature API Teams
- Why build, maintain, and support a Developer Portal?
- Summary: Social Practice applied to APIs and DevPortals
This article is based on the presentation given by Kristof Van Tomme, Pronovix Developer Portals co-founder, at API Days Interface in July 2021.
How to build a successful API program using social practice theory
One formalized way of thinking about what it takes for people to start adopting a certain practice—such as using the APIs available from your developer portal—is Social Practice Theory. Social practice is a theory within psychology that seeks to determine the link between practice and context within social situations (wiki). Social Practice Theory has been used, for example, in figuring out ways for people to take their prescription medicine: having access to medicine at home versus taking the medicine on time.
There are three components to Social Practice Theory: material, competence, and meaning. For APIs or integrations, competence relates to the people both creators and users; the material—or tool in this case—are your APIs, your API gateway, or your developer portal that you need developers to adopt for their use; and the meaning translates to the purpose or business drivers for your portal.
When we at Pronovix build developer portals, we ask:
- How can your developer portal help your API program to succeed?
- How can your organization become more resilient through the use of APIs, integrations, and digital experiences?
- How do you create a successful API ecosystem, for use both internally and externally?
The Tool Utopia Trap for DevPortals
The tool utopia trap suggests that if you buy this product it will solve all your problems. The truth is that no product solves a problem without the people who use that product—no product is successful without adoption. Tools give us power, but if we do not use them correctly no work will be done. Imagine placing a nest in a birdcage, expecting that it will just grow birds.
The other problem is that a tool like a bird’s nest will start degrading from the moment the birds leave. The more turbulent the environment, the faster a tool will start decaying. Decay is especially problematic with software that lacks a clear and sustainable business strategy. Incidentally, this is why Pronovix has started the Developer eXperience Management (DXM) initiative to help its customers to not lose sight of long term strategic goals set around their developer portals and API programs.
Tools without people are useless, it is the practice of creating, maintaining, using the tool that makes them valuable.
When we look at a product, consider the people on the inside (upstream), and the outside (downstream) of the organization, their behaviour patterns and their long term health. Unsustainable practices on either side will endanger the long term survival of the product, because the technology without people is just an empty birds nest.
When suggesting that APIs should be developed as products, this suggestion includes thinking about the people who are creating and maintaining that product.
The moment you involve people into a process of using a tool, the whole becomes a Complex Adaptive System.
Complexity arises when a set of agents have the right level of:
- Interconnection
- Interdependence
- Diversity
- Adaptivity
Products are interface boxes around and between Complex Adaptive Systems.
The people who make up Mature API Teams
A bird can build a nest. But not all birds build their nests well. One bird builds its nest in the wrong location and just as the eggs have been laid a gust of wind blows it over. Another bird, with much experience, returns to a tried and tested location and builds its nest to be robust.
Teams that create developer portals rarely lack a product owner and API developers. However, they often lack technical writers and developer advocates. To be successful, you benefit from including the mindset of technical writers, as you think about information architecture driving the documentation needs of your developer portal. If you don’t have good documentation, the developer experience will not be great.
If you are serious about successful promotion of your APIs, you probably need a developer advocate. The difference between internal and external developer portals is important.In case of an internal API program, you have a protected context and group of people. It’s possible—but not easy—to influence their way of thinking using domain models created over the years by business analysts. You might want to recruit an internal developer advocate. With an external API program, you need to think about your developer relations (DevRel) program, and recruit external developer advocate(s).
Most organizations don’t have these capabilities in their team—at least not from the start of the API program. This leads to considering the meaning of a social practice.
Shared meaning happens when a group of people develop an understanding about a certain topic that they share. For example, a single Tolkien language is a code understood only by readers of The Lord of the Rings. It is just a tool for encoding information, in this case creating a fantasy. However, a real language happens when there are multiple people, culturally connected, using the same language to connect with each other and to build shared meanings.
Why build, maintain, and support a Developer Portal?
Birds don’t grow nests, they meticulously build them. Why do they do that? How did they retain or develop this capability, and how come almost every bird species builds nests?
The pattern has an interesting connection with humans: there is a shared social meaning in nests. Nests are social constructs for birds. In this case, social meanings are genetically encoded: mate selection, procreation, raising offspring. The shared social meaning between birds reinforces individual practices. This shared meaning of nests among birds is similar to how social practice works in human systems, but in the later case, social meaning is usually culturally encoded.
“I believe just like the team that builds the API helps with the tool, the role of the developer portal is to help with the creation of shared meaning.”
You create and publish API documentation through the devportal, but there is much more to it. Have interaction to help people form a mental model of what your APIs do both individually and in combination with other APIs that you have. We think the need for mental models to put tools to use is leading towards that affordance catalogs.
In the devportal team you will need a shared meaning about what exactly the team is trying to do, you need both the tool and its competencies.
An affordance of a product is also a socio-technical construct: a capability that is attached to a product that people have gotten used to. People know they can do something with a certain tool, you need the two together to create an affordance. An example here is the decision by educators to use Zoom or Google Hangouts as a classroom space for children although the technology was originally designed as a business meeting space.
As Michael Hibay highlights, we should have affordance catalogs rather than API or service catalogs. It’s not that obvious how such an affordance catalog would be for APIs, we are currently thinking of ways.
Summary: Social Practice applied to APIs and DevPortals
When you build an API, a developer portal, have an API management tool or use any kind of tool, somebody has to maintain it. Not every software tool requires the same maintenance, just like a hammer doesn’t need much care but a car does. But API software exists in a turbulent world, and you cannot afford to not have maintenance or not continue to develop your products.
“The more turbulent the environment the tool lives in, the faster it will start decaying.”
Maintenance practices are important in the software world, especially with APIs. APIs are even more abstract than software, and especially vulnerable once humans are not there to defend them. To read more on this topic, see our article on the 4 Most Common API Developer Portal Mistakes where we investigate developer portal anti-patterns - common solutions to developer portal problems where the solution is ineffective and may result in undesired consequences.
To be able to have an API consumption practice, where you use an interface, you also need an API production practice, where a team is producing the interfaces and documentation that will be consumed by other people. It means these tools—integrations—are interfaces between two groups of people.
“Whenever you are looking at an API you should be thinking about two sets of people. You cannot look at a tool without thinking about both the people that will use it and the people who will build it.”
If you are thinking about the tool without the people, you are going to step in the utopian tool trap. We suggest rather thinking about the tool as a cell, which is separated from the rest of the other parts of the equation through an interface. Inwards from this interface there is a group of people creating their shared meaning about what the tool is supposed to do. Maybe that meaning is shared with people consuming the APIs. Allow for affordances.
When you start thinking about using a tool, we suggest to first ask:
- What is the product’s promise that is being made?
- What promise am I making to myself?
- What competencies will I need to be able to use this tool?
- What practices do I need to do to be successful?
- How will you build shared meaning so that we can effectively implement the practices?
Final words:
Don’t take the product promise for granted. If you want to be successful with your API program you will need ongoing processes to maintain and promote the use of your APIs. We believe that the full potential of any API program will only be fulfilled if you can engage people’s minds and create a meaning that is shared by as many people as possible in your organization.
All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.
