Application programming interfaces (APIs) are fast becoming the global standard for automated data exchange between and within companies. When a company first launches APIs, an adjacent step is to set up an effective system for automating API planning and implementation. But beyond that, as companies grow and expand their API use, the central challenge becomes figuring out how to best position APIs for scale as multiple, distributed teams build APIs across business units, often around the world. 

Failure to scale well in this environment is common and can drain time, money and resources, while creating employee stress and system compromise. But every enterprise can avoid pitfalls and successfully scale well-designed, consistent APIs across many teams by following concrete steps that align those teams on standards, through collaboration, and the right tools. Let’s take a look at the steps. 

Use design-first API principles that honor the app builders

Fundamentally, I encourage teams to apply design-first principles and Product Management processes to their APIs. This means considering one’s business model as well as the needs of the customer’s APIs – that is, the needs of the developer community—before building APIs. Design-first means making sure APIs are designed according to verified use cases from the developer community. 

Rather than designing APIs based on existing backend infrastructure, teams should ask: “What are the kind of applications we want to see built on our platform? Who are the developers building them? How can we make development as easy as possible for them?”

Kong offers a complete ecosystem of tools to cover the product development process for designing APIs—from writing API schema to implementing and launching to testing and debugging with Insomnia to creating API documentation. But for a growing enterprise, that’s only the start.

Understand that teams are decentralized and autonomous

As companies grow, money quite rapidly from “unicorns”to “decacorns” with thousands more employees during the recent pandemic years, APIs will not be designed by just one team applying product principles.

Instead, segmented product teams, each of which need their own APIs, will form, and they will vary in terms of skill and experience in applying design-first API principles. Even if these teams do implement well-designed RESTful APIs, these APIS are unlikely to be consistent across product and business units. Developers using the APIs will notice the inconsistencies, and may find themselves unable to build applications that work seamlessly with a company’s various product lines. 

Disjointed APIs can lead to disjointed integrations, more effort and frustrations for external developers, and more room for bugs in these connected applications. Decentralized teams are a necessity in enterprises, and they must have the autonomy to plan their own APIs. But there must also be effective mechanisms in place to make sure APIs from different products work well together, through design consistency. 

Facilitate standards with a central API team and API Council

In general, that consistency should be the responsibility of a central API team, but it’s not a team that’s dictating rules. Rather, it’s a team that works cross-functionally across product areas to facilitate standards, supported by all teams building APIs, often through some form of an API Council. In a council, everyone working on APIs may regularly share their experiences working with the developer community, to coordinate on API standards. 

Such standards extend industry standards such as RESTful design, with additional requirements to ensure that their APIs have consistency while still planned by individual teams. The council considers, for example, property names that will be reused, property requirements for inputs and responses, how models should be structured, how pagination, sorting and filters should work, and other design and implementation details that make the developer (customer) able to more easily build apps that work with various APIs from different teams.

Enforce council decisions with an API linter

A well-organized and well-coordinated API Council can produce and document the company’s API standards, but enforcing these standards  is another challenge. It’s best to go beyond mandates written down in internal documentation somewhere, and rather with a set of tools to help individual teams design their APIs more easily – and in the process, align to establish standards. One key component to this strategy is the API linter.

API Editors such as Insomnia commonly help to check that an API is RESTful, but a linter also ensures that custom requirements set by the council are honored. Teams thus maintain their freedom and responsibility to plan and build APIs, while the linter can make it easier to design and implement APIs that are aligned with company standards. 

Linters work easily in Kong’s ecosystem, with Insomnia during testing and within the CI/CD process to make sure that the APIs built are high quality and still aligned with the standards as they go live.

Share and reuse models to encourage consistency and collaboration

One of the most important steps to ensure that companies position their APIs to scale is sharing. As teams plan and develop APIs, they will create certain API models that are useful across other teams. Sharing those designs and making them easily reusable across the company ultimately will help developers building applications. 

Sharing functionality can be used in API editors like Insomnia, whereby established models for reuse can be made accessible to all teams for their API designs. And, like the linter, this kind of component in an API ecosystem helps teams scale.    

Address the “little things” with shared implementation tools

Tactically, getting teams and tools and processes to work smoothly is complicated. Little things crop up that can interfere with API quality, and some teams are better than others about addressing them. For example, establishing an automated system to create API libraries can require extra attention to run smoothly among multiple teams. 

Whenever a team wants to update an API, it’s nice to have libraries that can be automatically updated along with new API enhancements. Common automation tools can be janky and require additional tweaks when applied across different APIs. Make sure teams have what they need to do in order to design their APIs to work well with any API library or SDK generator.

Align disjointed teams with a well-configured API gateway

It’s vital for the central API team working on standards to work with the infrastructure team for consistency in the underlying layer of their various APIs. For API infrastructure, the API gateway is a core component to any plan for scale,   making many problems of scale disappear. 

For example, as companies grow rapidly, teams can become so disjointed that API rate limits aren’t even consistent. Rate limits curtail the number of requests that come into a server so that an API isn’t overloaded as it grows in popularity or overwhelmed by too many requests by one application, sometimes malicious, sometimes by accident. 

Teams using a well configured API gateway don’t have to think about rate limiting rules because the gateway can be tuned to ensure consistent limits across all APIs, as long as all APIs are consistent in their underlying infrastructure. The API builders and the developers consuming them just won’t have to worry about problematic rate limits at all.

A similar benefit holds true for authentication and authorization consistency. A well configured API gateway ensures that API Product teams do not have to write their own code to handle different means of authentication, nor do they need to prompt their users to authenticate multiple times for access to different product areas. Aligning scopes and permissions via the API gateway fortifies security and helps create a much smoother experience for developers building apps that work across a company’s APIs. 

Be tactical about monitoring and analytics

A well configured API gateway also can improve the tracking and monitoring of APIs and the data collection that can optimize an enterprise’s whole system. Consider a typical enterprise scenario where the company’s data scientists are forced to write custom code for each API to get data into a central repository for analysis. Because of variation among teams, they end up having more data on certain APIs than others and deep inconsistencies. 

In comes an effective API gateway with a built-in analytics tool, built-in monitoring, and plug-ins for other means of observation and evaluation. With every team on this same gateway, it becomes much easier to collect data and bring it into a centralized system in a consistent format. The data science team is able to understand and leverage data much more quickly for the benefit of the business—whether that’s to understand application consumption by customers and partners or to analyze API flaws to improve security. 

Consider what the future holds for API design simplification

The challenge of scaling APIs, their ecosystems and teams has been around for more than a decade. But as API communication increasingly becomes the dominant form of data exchange for businesses, maintaining solid API designs long-term becomes more important than ever. Everyone working with APIs should keep a close eye on tools that simplify design and implementation, while improving security.

Right now, schema decorators are on the rise. They are tools that can take an open API schema and enhance it—to automatically generate the definitions of endpoints, for example. This sort of functionality may be helpful in enabling consistency across APIs, with general standards applied automatically for API product teams. 

Additional examples include converting loosely-typed API schemas to strongly-typed schemas, using mappings to apply formatting rules established as part of a company standard. Such tools have begun integrating into API editors as well. 

Scaling APIs

It’s up to everyone working on APIs in growing companies to think about scale and how each of us can not only use these steps but contribute to the community of continual improvement in API planning, design and implementation. We do it not just for one team but across teams for the whole organization—setting and sharing standards in a collegial environment that keeps us all committed, coordinated and consistent.

Watch my full session from Kong Summit where I discuss this topic in detail: