Cloud Hosting

LONDON — “If API governance and platform engineering had a Venn diagram, they’d be a circle,” contended Mark Boyd, director of Platformable, during his keynote at the API Conference April 10.

He doesn’t distinguish between your API governance toolkit and your platform engineering strategy. And maybe you shouldn’t either. After all, both prioritize the same ideal customer profile: your internal developer colleague.

Indeed, APIs have emerged as the preferred way that developers want to access and build on top of any internal developer portals and golden paths to production. And a focus on API and data standardization and cross-organizational service reusability is at the foundation of any platform strategy.

“The API is the tail wagging the dog,” Boyd argued, “as so often APIs can fundamentally change the business.”

Externally available APIs create an ecosystem around the business, he said, opening up new routes to market. APIs become a cross-functional language that allows both technical and business stakeholders to communicate. And, he said, building an API ecosystem with different business units allows for cross-organization collaboration — like via an internal developer platform — instead of fostering internal competition for time and teams.

This is especially relevant today, at a time when everyone is trying to do more with less, to increase developer productivity right when developer burnout is running high.

So what does a lightweight API governance strategy look like? How do you overcome API complexity? asked the APICon audience. Here’s how to streamline that complexity now.

How does an API life cycle start? Usually in isolation. An API user, Boyd reflected, needs something and the solution architect looks to either extend an existing API or, more often, create a new API. A product manager may be involved but only at the beginning stages, for gathering requirements.

There’s very little checking what’s already out there — likely because there usually aren’t simple ways to do that. And there’s rarely standardization around APIs to boot.

Only about half the APICon audience raised their hands when asked if they use API specification formats like OpenAPI, AsyncAPI and AWS RAM. Use of these formats can cultivate uniformity across an organization and potentially save time, as at least this activity means there’s a definition of an API written out in an understandable and consistent format.

In addition, only a few members of the audience said they created or reused data object schemas: meaning each API could potentially use a different data model to describe the same sorts of things.

Boyd gave the example of a user account: each API may create a user account data model slightly differently: some may use FirstName, LastName, title, organization, and email, others may make one field name for first and last name, and then just ask for an email address, while others may have even more fields.

To apply API governance when creating a new API, Boyd recommended you begin by mapping out the developer’s journey. Ask: What are the pain points? What programming languages do they use? What architectural patterns do they rely on?

Write down your use case description for the API at the start — not just the API name, he emphasized. This practice helps the API architect verbalize what their API is intended to achieve. This description can then be included at the start of your documentation, which increases discoverability, which in turn increases reusability. And, if you’re planning to expose your API and documentation externally, it increases your human and machine-readable searchability.

“That sort of little user story templating helps stop developers [from] leaving their flow and thinking: OK, what model should I use?” Boyd said.

It also helps with API discovery and reusability across the organization. Everything becomes more easily searchable through an internal developer portal or API catalog, so this API will be more likely found and reused, which is much cheaper than building from scratch.

Finally, as we move into the generative AI developer productivity space, this quick exercise of jotting down what an API is intended for also makes it more machine-readable, which increases the possibility for it to be suggested by a GenAI coding assistant. These steps help decrease interruptions to developer flow and eventually save time and money, as developers focus on new, differential work.

To help foster even more design thinking, Boyd also recommended writing a press release, even if it is likely never to be shared.

“Imagine it’s the end of the project. You’re releasing that API, or the new features of an API. And you’re describing it externally, what’s it going to do? What value is it going to create for others? How will people use it?”

He said this public relations practice “will help clarify your thinking about all of the things that you need in that API as well.”

Platform engineering is a sociotechnical practice that looks to reduce the complexity and cognitive load that comes from disparate tooling, by creating a single pane of glass view of shared services to better serve the internal developer. API governance via a platform or internal developer portal enables service and API reusability, instead of teams building everything from scratch.

A key pillar of platform engineering is the laying down of golden paths, which Boyd called “agreed upon architecture.” These are typically the simplest way to accomplish a repeated activity. By clarifying these paved routes, organizations typically see a reduction of complexity and developer cognitive load, which in turn speeds up the delivery of value to the end user.

Since Conway’s Law reigns supreme, communication structure and technology are intrinsically linked. Boyd offered up another platform favorite, Team Topologies, an engineering management system that can help organize teams around a new way of shared API governance.

Introducing a Team Topologies approach requires organizational restructuring and reallocation of resources from stream/line of business teams to a centralized platform team, and giving them the authority to support line-of-business teams to use common tooling across the organization.

“Often, APIs have gone out to lines-of-business where each line of business has their own API teams building their own APIs independently,” Boyd said.

Much of the tech industry is moving slowly toward a platform team that offers centralized services to what Team Topologies refer to as stream-aligned teams. It doesn’t enforce API governance on these teams but rather a Platform as a Product mindset compels these stream-aligned teams to adopt golden paths because it’s just easier. You might have to persuade teams that this is indeed the path of least resistance.

Teams may push back, Boyd warned, claiming, “Our line of business is very unique and very special.” Not every team has to follow your golden paths, but the platform team must persevere in its attempts to centralize resources common to the whole or the majority of business lines.”

This can include the API catalog and an API management solution.“Even the developer personas could be owned by that sort of central team,” Boyd said, “because those developer personas might be matching for multiple lines of business.”

Just remember to start small. He emphasized the importance of API documentation and cross-organizational API discoverability as the first steps to the thinnest viable platform. Because, judging by the reaction of the APICon audience, very few platform teams have big budgets, so you’ll have to work with what you’ve got.

We are constantly in a state of bundling and unbundling in the tech industry, Boyd said. The popularity of platform engineering and Team Topologies is just that pendulum swinging back from the recent extremes of developer autonomy toward re-bundling common services. In a time of trying to do more with less, this is sensible, but also it helps address tool overload and cognitive load.

Often In the API development stage, “I see the product manager being released from their duties too early,” Boyd said. And then they aren’t often brought in until the API is ready for deployment.

“We need more product managers in the room,” he said to an audience of mostly AI architects and API engineers — and only one API product owner.

This is a mistake, he argued, especially when your API catalog and developer platform need to be “sold” to your internal customers. Plus, it’s unnecessary to exclude them since, when using something like the OpenAPI specification, you are able to communicate in a human-readable way that allows business and tech to communicate more easily.

“You can walk through it and talk about what some of the functionalities you’re exposing are and just double-check that [it] matches those functional requirements that they’ve helped identify in the first place,” Boyd advised.

While the product doesn’t stick around long enough, security often isn’t brought in until the end of API creation, which risks not just code security and stability, but all that work being for naught if security doesn’t clear it. It’s especially important to bring security in early, he said, if the API is going to expose any data or services externally, “so that you don’t have to remake those decisions.”

Security guidelines are an excellent way to address security early, he said. When his team at the data and tooling startup Platformable works with clients to write an OpenAPI specification, each item of data in a model that’s being exposed is given a risk factor — low, medium or high — considering an organization’s data sensitivity, compliance risk, and brand risk. The higher the risk, the earlier in the API development life cycle you bring security in.

An API style guide contributes to that consistency that drives reusability, but it isn’t something you need to create from scratch. The API Stylebook is a collection of guidelines and resources for API designers. Boyd touted Zalando’s RESTful API Guidelines and the Adidas API design guidelines as exemplary.

Since APIs expose data, API governance is really about data governance too, he contended. “What I see in a lot of businesses is API governance and data governance are seen as completely different.”

Since APIs are usually scattered across organizations, API architects can make the lives of the data teams easier by creating an agreed-upon taxonomy of functionalities. This can include setting field standards, like trying to influence whether to use “user” or “account,” and whether you use “first, last” in a single field or in separate fields.

When moving to an API governance model, you don’t have to go back and update all your APIs, he said. But you can follow those outlined steps when designing new APIs and when updating older ones.

Follow API architecture influencer Mike Amundsen’s advice on guide implementations with the EASE rubric, Boyd said, which helps you assess whether to go back and refactor existing legacy technologies to meet new governance guidelines. The EASE rubric considers four identifiable qualities:

“A key thing to keep in mind is that not all solutions need to excel at all four qualities. If the API is only used internally by a single team, then it is likely that it will have only minimal scalability and efficiency,” Amundsen wrote. “And might only need a bit of extra work in order to meet availability needs.”

But if an API is to be exposed or have a cross-organizational functionality, it needs to score high on all four, which means it is more likely that the new API governance framework you are introducing (such as style guides) should be imposed.

API sprawl is something the industry has been grappling with for over a decade now triggering a huge discoverability problem. For too long, siloed teams have been using APIs as a way to connect both internal and external services and data with both internally and externally created APIs.

No organization really knows how many APIs are connecting which services and exposing what data. This makes both API standardization and security more challenging.

Fortunately, Boyd argues that the industry’s scaled adoption of internal developer portals is really just another — perhaps more efficient — way of approaching API portfolio management. Specifically, since a great early win of any platform engineering initiative is service discoverability, anything that can facilitate the creation of an internal API catalog is welcome.

“With internal catalogs, at least all of the APIs could be listed in one place so people can see. You can actually have in an internal developer portal the data models as well, so people can [also] reuse those.”

His team is trying to cultivate a developer’s reflex, he added, so that “whenever you have to build something new for your API, you should be thinking, ‘Hang on a second. Let me check the internal catalog to see whether or not we’ve already got one of those’” data models or APIs.

Boyd mentioned four different internal developer portal tools:

He also suggested looking at Stoplight, recently acquired by SmartBear, as an API design tool. “What I love about this is you can actually define your style guide in it,” Boyd said. “And then, as you’re building your OpenAPI specification, it’s telling you whether or not you’re out of bounds from your own style guide.”

If you have an external API ecosystem, you can even publicly release your style guide. Stoplight also maintains Spectral, an open source linter, which can check your API design against your style guide, industry standards or more widely accepted API design best practices.

He also recommended running all your APIs through 42crunch, an API security platform that can take an OpenAPI description and assess its robustness. He also pointed to new open source tools that perform similar assessments, such as the recently released open source OWASP Ruleset.

But, as he said, the immense API Landscape is continuously expanding — particularly if you follow Boyd’s overlap of API governance and platform engineering. To date, it features 2,159 API tools.

No matter what you choose — and whatever you call this strategy of service and API standardization and reusability — Boyd urges that you remember your internal developers are your customers. You should be publishing your roadmap and sharing it with them to get feedback. This also enables inner sourcing where you can leverage the work of developers organization-wide, which is especially important in these tighter times.

And of course, measure the results of your program. Some metrics you could track include:

“Your metrics may vary,” Boyd emphasized, noting many of these ideas were presented by John Musser in his work on Ford’s platform engineering program. One key metric his team uses is developer days saved per project and overall, calculated as a monetary value of dollars saved by the organization by introducing standardized approaches.

Kick-off any API governance or platform engineering initiative by asking your developers what their pain points are, and craft your strategy from there. And keep track of data like the four golden signals — latency, traffic, errors and saturation.

When in doubt, creating an ideal developer flow, Boyd said, should look to continuously answering three questions:

Just remember, he said, as you face this complexity: “You’ve got to start small and show the benefits to your team and to all decision makers involved.”

YOUTUBE.COM/THENEWSTACK

Tech moves fast, don't miss an episode. Subscribe to our YouTube channel to stream all our podcasts, interviews, demos, and more.

SUBSCRIBE

Read the rest here:

Is Platform Engineering Really Just API Governance? - The New Stack