The API Security meetup in Cincinnati had a panel discussion this month and the topic was “Developer Portals”. When we were planning this, it seemed like it might be a pretty dull talk. How much content could we squeeze out of how a few companies went about creating and maintaining this very niche part of their web presence? Luckily, we gained some interesting insights into how three Cincinnati companies (Kroger, Paycor, and P&G) keep their developers happy with their robust offerings.
Let’s start off with defining a few things about what a developer portal is. When companies want to expose functionality externally to web developers, normally through a curated set of APIs, they set up the portal. In addition to the API definitions, there can be a lot of useful content like style guides, examples, documentation, and support resources.
The first question posed to the panel was regarding “Buy versus Build”. There are vendors that play in the API space, like Kong and Azure, which offer a plug and play developer portal with their tools. These off the shelf portals can allow teams to quickly get a portal in place quickly, but all of the panelists agreed that there were too many limitations with the ready to use offerings. Kroger and P&G called out the need for controlling the aesthetics and the user experience as a core reason to build. Paycor liked the control and the ability to pull in open-source tools to facilitate the build process. Robert Buchannan from P&G noted that you need to be ready to defend the decision to build because many peers will ask “why not just buy it”.
The discussion next turned to the target audience of the developer portal. Paycor called out their clients and partners as the target audience. Kroger noted internal and external developers, while P&G stated that their current focus is on internal developers only. All panelists agreed on the need for role-based access controls (RBAC) on the portals. This gives granular levels of access to different types of users based on what they should see on the portal. Internal users might be allowed to see everything. External users might only be allowed to use the public APIs. Trusted partners might have a mix of both.
Our panelists next discussed the life cycle of their public and private APIs. Paycor and Kroger both talked about the need for stability in the Public APIs. Public users and partners need stability in the contracts of the APIs so their solutions keep working. While the contracts may stay the same and still show a v1.0, all of the speakers talked about how different the functionality of the public APIs change behind the scenes quite often as the internal mechanisms and APIs evolve and mature. P&Gs main advice was to make it easy for the users with simple APIs and good documentation.
The next topic the panelists discussed was the metrics they found to be important. Paycor stated the desire to see how often APIs are being called to measure adoption but noted that they like to see that rate stabilize over time to see some stability. P&G noted that the number of clients is a key metric to show that your APIs and developer portal are easy to use and are readily used and adopted by new users. Kroger called out the desire to measure how quickly a developer can get a new API into the gateway can called for the first time, but also noted that this is difficult to measure.
The final topic of discussion was about the quality of the documentation presented on the developer portal. Kroger was fortunate enough to have two technical writers who were dedicated to creating the initial style guide and user documentation. This gave a very consistent voice to all of the documentation. Paycor was focusing on publishing accurate contracts and some detailed ‘how to’ documentation. P&G is currently focusing on adding a lot of code samples and Postman examples in their documentation. All the panelists agreed that the best way to determine if your documentation is good is to use it yourself. Kroger gave a parting guidance stating that the corners you cut in creating quality documentation will be given back in support time.
In conclusion, the API Security meetup in Cincinnati provided valuable insights into the world of developer portals, showcasing how companies like Kroger, Paycor, and P&G are navigating the complexities of creating and maintaining these crucial tools. Whether discussing the buy versus build dilemma, defining target audiences, managing API life cycles, tracking metrics, or ensuring the quality of documentation, the panelists emphasized the significance of thoughtful design, user-centric approaches, and continuous improvement. As we reflect on their shared experiences and wisdom, it's clear that investing in robust developer portals is not just about technology but about empowering developers, fostering innovation, and ultimately driving business success.
