6 Questions on API Governance
by Raymond Xu. Read the original article on Medium here.
“Software is Eating the World, API is Eating Software”. The quote, as widespread as it is, is absolutely true. APIs are serving as the backbone for the majority of software infrastructure.
According to Akamai, the world’s leading content delivery network (CDN) provider, 83% of its traffic came through APIs. All Cloud operations, IoT connections, data algorithms, autonomous driving, digital twin initiatives, meta universe and much more are based on APIs.
However, the governance of APIs is a relatively new challenge for IT executives and managers across the globe. Many questions have been asked again and again at the Board rooms, company conference rooms, online chat rooms, or any rooms alike.
Here I capture six most frequently asked questions. Not to answer those mind-bogging questions, but to offer some perspectives, some counter-arguments, some thought-starters, some lessons-learnt. The target audiences of this article should be IT managers, product managers, corporate executives etc., less for API developers and designers. But the API developers and designers certainly have a big stake in this and are critical participants and contributors in these discussions.
Q1. What is API First?
API First means different things to different people.
For API designers and developers, API is a contract committed between the API provider and API consumer so that both know the interfacing parameters. API First development means that teams define upfront business contracts between each other using API mocking, before developing the individual API. By defining the contract first, this enables the teams to work in parallel as the respective producers and consumers of the API. This also enables the hardware and software teams to work in parallel as the critical path dependency between hardware and software is now broken.
For IT executives and managers on API governance, API First is the strategic priority to a company's strategy, organization, operation, business model, product development and much more.
There are no better insights than this article: “What is an API First Company?”. Kin Lane, the Chief Evangelist from Postman, highlighted 13 distinct areas that make API First company stand out from those who are earlier in their API Journey. “Companies who have moved their operations into an API-first world see APIs as key to not just doing business, but defining how business is done within their industries. This is about prioritizing what you are doing behind every aspect of your operations in a more organized and deliberate way,” stated by Kin Lane.
To most IT and business people, API First is the culture shift. No longer the monolith application development from end to end, but many loosely-coupled microservices to speed up the end product development. No longer the heavy-handed planning and governance from the central team or higher management chain, but grass-root API development to deliver the business needs at Agile speed. No longer I develop it and I use it, but everyone leverages internal teams and external partners to serve the boarder ecosystem needs.
So API First means empowerment to the developers, agility of software development, and democratization of corporate IT. API First is the culture shift.
Q2. Who Develops Which APIs?
Who Develops Which APIs? This is the most politically sensitive question in the siloed and layered big corporate arena. Some managers immediately try to retro-fit API structure towards organization structure, or vice versa. Some argued that the data owner should develop the APIs. Some stated loud and clear that the incumbent application owner should develop the APIs. In the end, all these still come from the old mentality: I own it, I develop it, I use it. Treating APIs as another power grab/struggle in the corporate world.
Democratize API development. Some high capability APIs, some external facing APIs, some PII-sensitive APIs, some enterprise-level APIs, do need senior level management and architecture review and care. Some foundational APIs that serve the common enterprise needs may need to be developed by a central/foundational team. Most APIs serving the integration needs will be grass-root developer’s call to design, develop, deploy and decommission.
The immediate business needs and development needs will drive the growth of most APIs, not a small central planning team. The drawback is potentially too many short-term-focused, sub-optimized APIs. But “Do Thing First” mentality won over.
Democratizing of API development, and associated competitive pressure to develop and use the best APIs, will eventually evolve APIs to healthy and valuable outcomes.
Q3. Who Is/Should be the API Owner?
API owner is the person who has basic understanding of API business value, tech spec, hosting gateway, consuming applications, development cycle plan etc., has empowered authority on API lifecycle and management.
If we truly treat API as a Product, then the answer appears to be obvious: “API Owner is the Product Owner”. In reality, it is not so obvious: In some companies, the Product Owner is a business person who may not know how to spell API. Preferably, an API owner should be an IT person.
Then, what kind of IT person, or at which level, should be the API Owner? IT Product Manager? Tech Anchor? Software Engineer? Is there a need to retro-fit API ownership to the organization structure, i.e. listing all supervisor, manager, senior manager, director etc. as the owners for one API?
API as a business service or product, sometimes it has greater value to have a business person to own an API, especially when that API is serving external applications and has monetization value.
Sometimes the true API ownership goes out the boundary of your team, your division, your company. API can be provided by a remote team, by a vendor (SAP), by a start-up (Clickhouse), by a service org (weather.com). In this case, an internal representative is needed to serve as the liaison for an external API and own the relationship, operation performance and usage cost etc.
Some traditional application owners have strong desire to “own” the underlining APIs. “How can I know what happen to those APIs my application is using?”, a valid concern from many application owners.
But the solution is not to centralize the ownership, not overwhelm one manager, but democratize API ownership, with light governance and strong guide-rails.
Q4. How to Govern APIs?
If treated as a business product, API can be governed by business units. If as an IT asset, then governed by IT management and architecture committees. If as a set of software codes, then managed and tested by other software codes like Linter.
But somehow API fits all the characters of above, then should apply to all the disciplines to API governance? Or should we focus on one primary discipline? Or is there a balanced and federated approach on API governance?
In the industry, the balanced and federated API governance is gaining traction.
First accepted practice: not heavy-handed central governance on API review and approval by layers of management or architecture committees. Layers of committee reviews will certainly slow the development and innovation. But it is not all to be determined by one or two developers under their fingertips. So where is the mid-ground?
Stripe’s API are reviewed by a pool of cross-functional reviewers with documented outcome and average one-week window. For Meta (formally Facebook), the executive approval process is required for external-facing API upgrades. The mid-ground is the tailored governance based on competence, risk, impact, revenue etc.
Second accepted practice: API is a code, certainly can be tested by other programming codes. The API Linter provides real-time checks for compliance with many API standards. The Linters can be tailored to many organization’s API standards, even naming conventions. 42Crunch is another tool to test your API codes. But any programming based testing is never enough as API development and security is ever evolving. The code may never address all standard deviations or security threats.
In combination, many companies are taking the balanced and federated approach on API governance, and leveraging many tools, progresses and people in concerted efforts. In the area of API monetization, pricing is still very much manual, but tracking is very automated. Even in API portfolio management, normally a very people-intensive area, is also transitioning to the federated governance model.
Q5. How to measure APIs?
The rudimental API measurements are the number of APIs and the number of API calls.
Based on various survey results, an average company now owns over one thousand APIs after a few years of API development. As the number of APIs grows, the portfolio complexity grows at a much faster pace.
Even the number of API calls is not the best measurement for the success of API in any company, but it does indicate the scale and complexity.
API is a business and technology product. So it should be measured both by business metrics, like revenue per million calls, variable cost per call or per API, fixed cost on infrastructure and development, return on investment, etc.
But it should be measured by technology metrics as well, like performance, latency, versioning, utilization rate, re-use rate and much more.
Many companies develop many index metrics to measure multiple facets of APIs, then aggregate to one single numeric value. API Quality Index, Risk Profile, Re-Use Rate, are some examples of indexed API measurements.
Maybe the most visionary approach on API measurements came from John Musser, the Director of Data and Analytics at Ford Autonomous Vehicles of Ford Motor Company and the founder of ProgrammableWeb and APIScience. At his 2014 presentation, Musser proposed the most comprehensive measurements based on various roles, like CEO, CFO, Product Manager, DevOps, also based on various purposes, like internal integration, development efficiency, external monetization etc. In the end, Musser advocated to address “Who & why drives KPIs”, and “Prioritize and Repeat” the API measurements.
Q6. How to Name APIs?
If anyone reads the names of APIs from a company with less API maturity, he or she may get lost. If the development team is named as “Thunderbolt”, API should not contain the word of “Thunderbolt”. Just because API serves as the handshake between two systems, the API should not be called “Handshake”. If an API provides gear manufacturing analytics data, the API name should not be as stingy as “Gear Manufacturing”. If API is to provision a Virtual Machine, the API name should not be as abbreviated as “vm”.
If one API is to be used by an application, the API name should not be surfaced or prefixed by the application name.
Sounds funny? Right? But all above are real API names inside of some companies. Next time you call for the “Thunderbolt API”, you may trigger a thunderstorm with thunders over your head, or you may receive a thunderbolt cable to connect your computer.
Here are the guidelines form Google’s API naming convension:
Names used in APIs should be in correct American English. For example, license (instead of licence), color (instead of colour).
Commonly accepted short forms or abbreviations of long words may be used for brevity. For example, API is preferred over Application Programming Interface.
Use intuitive, familiar terminology where possible. For example, when describing removing (and destroying) a resource, delete is preferred over erase.
Use the same name or term for the same concept, including for concepts shared across APIs.
Avoid name overloading. Use different names for different concepts.
Avoid overly general names that are ambiguous
Carefully consider use of names that may conflict with keywords in common programming languages.
Overall, all API names should be: simple, intuitive, consistent. The majority of developers across the globe can easily understand an API.
Many companies are adopting more standards and processes to manage the names of APIs. Average companies have more than one thousand APIs now. Leveraging a company or organization dictionary is one good approach. The Linter tool can be used to check the API names. The company data model and business capability model are two standardized documents that can assist API naming convention.
Sounds simple? Right? API naming convention is a key component of API governance. Because intuitive and consistent API naming is not simple at all when API portfolio grows over thousands and API providers and consumers grow over tens of thousands people.
The governance of APIs is a relatively new, but growing, challenge for IT executives and managers across the globe. Many questions like above should be carefully debated and thoughtfully communicated. Above are not definite answers to the questions above, but more debates can lead us to better shared understandings and better practices on API Governance.
Read more from Raymond Xu on Medium: