Developer portals must evolve together with your use cases and APIs, be those siloed or centrally managed. The approach we suggest for iterative development is based on our 13+ years experience in technical documentation and 9+ years dedicated to developer portals.
Pronovix is a consultancy specialized in developer portals: we research, design, build, maintain, and support them. These are not portals that only evolve along a general SaaS path, but such that we also extend and evolve together with your needs at your speed, which is an important distinction. In this article we:
- Tell the story why we urge you to deliberately create and declare your interfaces,
- Explain why you need a flexibly evolving developer portal to do that, and
- Give a teaser of our framework for planning strategic investments towards a more mature portal.
As your API program expands and it starts touching additional areas of your business, your developer portal should mature to accommodate those changes. Especially in enterprise companies, we see the need for portals that answer the needs of a complex adaptive socio-technical system. Because developer portals are about more than just the technical integration, and APIs are not just IT tools. APIs are actually transformational: what is happening is a transformation of organizations and of society as a whole, and that is a big matter.
We hear from many organizations that their APIs–although historically they used to be part of their respective silos of origin–are now increasingly becoming the networked foundation that touches all the different parts of their business. Next to that, APIs are also enablers of a bigger interface transformation that is happening almost simultaneously in all digital domains.
Digital interfaces are also the agreements that make interactions easier
If you look at Application Program Interfaces, what A-P-I stands for, that Interface part is really significant. We normally don't pay attention to that word, but it plays an important role. Interfaces help our organizations to evolve and to adapt to the needs of the organizations that we are interacting with.
Interfaces enable us to structure and constrain how people in our organizations interact with people outside of the organization, and how we allow our customers to interact with us. If you look at the word 'interface', the dictionary typically will be defining it as the place or means for the meeting of two systems. But next to interface being a physical thing such as a door or a keyboard, understand that an interface is also the designed set of constraints and rules through which two systems can interact with each other. Interfaces play a crucial role in that they are agreements that make interactions easier.
For example, if you don't know who you need to contact for support for a certain product that you have just bought, how does one go about looking for that? Today, one would go look at a website and maybe start searching for a contact line. But if an organization publicly declares, 'This is how you are supposed to interact with us to do X,' that makes the interaction much easier for both their customers and the organization. Because you don't want to get requests that do not make sense in how you structured your organization or your business partnerships.
Think of, for example, the SWIFT system in Europe, compared to the costs the customers are made to pay by the banks if they want to have a non-standard financial transaction executed. The cost for routing unstructured requests is too high, especially at scale. You have to plan for who is going to pay that adjustment price, and create a more appealing, cheaper, and streamlined alternative.
Interface folklore: a plethora of organically grown interface conventions
Once you start thinking about interfaces, you see them everywhere, and it is fascinating. Interfaces are evolving and changing in nature. Because if you look around, you will see websites, numbers, addresses, applications, contact catalogs, and of course, developer portals and APIs. These are all places where you can go and find out how a certain type of interaction is possible with an organization.
Why is there such a jungle of interfaces? Take banking for example: user expectations about mobile banking and about internet banking are evolving. All these interfaces are usually highly localized and they are very specific to the domain. You have to get close to an organization to fully understand how you can go about interacting with that organization. The status quo now is that part of growing up as a human is learning how to find your path in this ecosystem. People bring their experience and contextual knowledge to this wayfinding -- and they often leave frustrated.
Deliberate and convergent digital interfaces
The big transformation now happening is that we are slowly but surely rolling out new interfaces across our organizations, in a much more deliberate way, and also in a more convergent way. Digital interfaces and digital technologies like APIs are helping to accelerate this expansion and unification at the same time. Certain interaction types are phased out from being the preferred action. Think of for example restaurant table reservations or take-away food orders: you can still call on the phone but it is just faster through the app. Support questions to large providers are routed to their knowledge base, and it is of late often practically impossible to get a direct phone call, albeit email is still a fallback option.
We are creating an alternative to human mediated interactions. Before, you had a specialist such as a sales clerk, who would be representing your organization, and act on your behalf. This specialist fulfilled a certain function, and followed certain business processes; these processes constrained how the specialist acted on your behalf. We are now moving towards more and more machine mediated interactions. In these, people still play a role, but where they are helped and what they can do is constrained through the design of the interfaces that they are using.
The illustration below is to show the evolution of this interaction design, mostly for B2B situations, but similar processes also hold true for B2C.
Before the advent of software and computing, as a basic interaction, you would have a human interacting with another human, to get a certain action happen, to get a certain job done. Then we created custom programmatic interactions, where software developers were coding the digital channel through which that human (to human) interaction would happen.
Then we built (web) APIs, and that enabled applications: a developer creates an application programming interface, that would then be used by another developer to integrate with some sort of programmatic back end on their side.
At the next stage–and that future to some extent is already here–we are seeing AI-mediated automated interactions. Here you have developers who are building the available interfaces on both sides, which interfaces are then connected to each other by a machine agent.
The key thing to notice is that these programmatic interfaces created for machine-to-machine interactions are sufficiently constrained, and so are the possible interactions. As genAI applications are per se non-deterministic, the constraints you design can make the interaction safe to the extent necessary or obligatory. You need that constraint so that the interaction will not be subverted, and you won't get unexpected outcomes. As you evolve your interfaces, you are going to get better with their regulation too.
The interfaces you expose determine the role you play in the market
As you are figuring out what APIs–and what other applications–to expose from the organization, you are architecting the constraints: the kind of interactions that you will allow your partners, your customers, your competitors to have with you. Be aware! It is a self-fulfilling design that needs your meticulous attention. Constitutional constraints, in turn, can become governing constraints. (If you would like to dive deep into the nature and dynamics of constraints, we highly recommend the works of Alicia Juarrero.)
However, if you don't have an explicit declaration of your preferred interfaces as an organization, in an AI mediated world–when it arrives–that is going to become an accelerated problem. We believe that developer portals are the most interesting pattern that can be expanded towards this much broader interface world. The things we have learned about how to make APIs discoverable and findable through developer portals inform us on how your portal, as a well-developed framework, can help transform how you expose your interfaces to the wider world.
The highly structured content, taxonomy, search capabilities, and both human and machine readability of a well-designed developer portal will also allow safely exposing your direct human contacts, the human interface to your organization, such as people in sales and support functions, for example. With such an interface portal, we could enable bots to do all the things. If those exposed interfaces are directly or indirectly APIs, then through the existing and evolving capabilities of observation and security for APIs, you can even protect your organization.
We could say that we are about to move from application programming interfaces–that are always about developers using an API to build a certain application or build an integration–towards application programmatic interfaces, where it is not necessarily a software developer person creating the connection but it could be an AI application consuming the API.
Interfaces both enable and constrain interactions, and by doing so, they help to protect your organization. These constraints at the same time protect what's inside and enable proper interactions with other parties. This setup also allows for later internal reorganizations without disruption in your data traffic relationships.
Interface portals
Developer portals are the practical primer for this larger interface transformation. We envision the portals of today to become interface portals expressly serving both business and developer audiences. You need to cater to both.
As you are walking your path of differentiation, to helping the world understand who you are going to be in this new, machine-mediated digital ecosystem, the portal you are building today will need to adapt. This space where you declare your preferred and available interfaces, has to evolve together with you as your interface program grows.
Existing developer portal SaaS products only address parts of this puzzle well enough. As we foresee these future transformational needs, we believe that a maturity model helps you to think in an evolutionary sense about your developer portal, about the roles it will play in the wider world. How can you accelerate and maximize the value that your portal will hold throughout the journey? We believe that this is an iterative process where you need to figure out what is going to be the value to focus on in each iteration. 'What are the dimensions we'll focus on right now? What's the first step we'll take?' Then we evaluate again, take the next step, evaluate again, and so on: this is an iterative process.
A maturity model for pragmatic evolution
What is the antipattern for developer portal maturity? Many API teams, mistakenly regard the developer portal journey as if it was a sequential one, and they almost always plan in three isolated stages:
They would start with, 'We are going to work on our developer experience. Help us to expose our APIs and to make it easy for developers to use them.' The preconceived notion is that there should be a second stage after a little while. 'Now that we have these APIs exposed, how we are going to make it easier to automatically publish updates onto our portal? How are we going to help to integrate this portal into our business processes so that the operation of our program becomes easier and we can save costs?' And also a third stage would be typically envisioned such as, 'In some distant future, we are going to monetize our APIs and make a lot of money.'
This sequential approach to stakeholder needs is dangerous. We have seen over and over that what might happen as a result, is that API teams would start with focusing purely on developer experience. Then address the operational aspects, which is also something that you can fairly easily get input on from your formula or the developers that are creating your APIs. And only then would the need for business alignment appear. This is where things get a little bit shaky. We know what happens often–and we have seen this a lot in the API community–is that you would have a very technical team super-focused on the first two aspects, but they don't really work all that much on the business alignment. But after some incubation time, comes their executive board, 'Tell me how much money are we making with our API program? How is this really contributing to our business?' Or, 'You told me that I was going to make a lot of money on monetizing APIs. Where's that money? You sold me an API marketplace. Where's the market volume? How much money are we making with this thing?' And there it gets kind of shaky and a little bit flaky.
Instead of having a predetermined maturity journey, we recommend a three-dimensional one-space maturity model. Instead of having this sequential approach, we help you think about how you can take at least some small steps forward in all three dimensions, in the way that makes sense for your business,so that you can go on this journey, and show value to your business owners or to your executives from day one. Start with a proof of value.
We see three dimensions enveloping the portal space:
- How can your developer portal reduce the time it takes for developers to use your interfaces?
- How well is your portal integrated into your company’s development- and organizational processes?
- How does your portal help you to create, protect, market, and capture value?
What we have learned is that each customer's journey is unique, and that having a developer portal evolving with them can make it easier to become successful.
We think interface portals will play a key function in interacting with customers: interfaces that are very very high in the value chain are part of your differentiation. It will be increasingly important what interfaces you expose and how you are exposing them.
At Pronovix we have chosen to be a consultancy (with a devportal platform product). We see that it helps our customers that we can go along with them as they go, at different speeds, either with continuous or with intermittent development cycles. If you are interested in taking the next step in all three dimensions and you would like to do a proof of value together with us, don't hesitate to reach out. We are always happy to discuss your case further.
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.
