OpenAPI Initiative

It time for our next Community Hero, and this time we talk to Leviathan of the API world Phil Sturgeon.

Phil is author of Build APIs You Won’t Hate, ex-WeWork system architect, ex-Stoplight product manager, and now working on Green Tech and API consulting.

Phil gave us some insights into the early days of OpenAPI, what he thinks would be great in version 4.0, and his hopes for a future of green software.

What drives your interest and involvement in the OpenAPI Specification?

The first time I tried to document an API I thought “this is a bit of a mess”, and for years it always was. It involved so much repetition, restating exactly the same interface already written down in integration tests, contract tests, serializers, validation logic, serializers… all in mismatching formats that needed awkward conversions at various phases of the API lifecycle.

OpenAPI appeared as the solution. It took a little work to get JSON Schema and OpenAPI v3.1 lined up properly, and various other corners needed rounding off, but getting involved with the OpenAPI spec and helping to define the OpenAPI-based API Design-first workflow has made life easier for API designers and developers all the way through the API lifecycle.

What do you consider to be your most significant personal contribution to the development of OpenAPI?

API linting and automated style guides have been a passion ever since working as a systems architect helping 100+ developers on various teams get started with OpenAPI. There was barely any tooling around for this concept and there were countless mistakes being made often, so I created Speccy to guide teams in how to avoid these mistakes in their OpenAPI and the actual API being designed.

This later inspired Spectral, and I joined the Stoplight team to help. As product & project manager of the open-source tool, and with a brilliant team, we created something so powerful that every major OpenAPI tooling vendor has integrated Spectral into their own tooling. It’s helping countless API teams around the world from tiny startups to massive corporations.

Automated style guides are now a regular part of making APIs consistent, useful, and even secure. For those working on API governance, it’s removed the most horribly boring and confrontational parts of API design reviews so that robots can handle all that rubbish.

Working on something as big as Spectral has been an amazing experience, even now as alternatives are gaining popularity, they are replicating its functionality and maintaining compatibility with the Spectral ruleset format. I love talking to these teams to help them avoid mistakes I made, share ideas we never got around to doing, and generally develop a better API linter so that the space can keep on evolving for years to come.

What do you see as the most exciting proposed features of version 4 of OpenAPI?

There’s a lot to be excited about, and a general tidy up and reduction in nested structures is going to help a lot of people not lose feeling in their fingers. For me the most exciting part is the increased use of standards.

Using JSON Schema to describe parameters via parameterSchema instead of a OAI Parameters Object will reduce complexity for tooling developers trying to figure out the complexities of style, explode, etc., something that is almost impossible to get right even if you dedicate your life to it.

Then of course there’s OpenAPI using proper URI Templates instead of something that looks a bit like URI Templates. Once again this makes life easier for tooling developers, but more importantly it will mean more powerful tooling coming quicker as these components can be plopped together like Lego bricks. This all means more options for end users and a better healthier ecosystem in general.

The OpenAPI Initiative is now a multi-specification organisation. How will the project change now that we deliver more specifications to the API community?

The extended Marvel Universe of OpenAPI specifications is getting really interesting, and it’s fantastic to see tooling vendors jump on board to integrate them into their offerings. This creates far more extension points and opens up far more interesting workflows for OpenAPI-based tooling.

For example, Overlays were initially thought to be mostly helpful to technical writers, but have finally solved the problem of getting generated SDK examples from one provider embedded in API reference docs using completely different tools. This allows tooling vendors and end users to keep working on imaginative integrations in a standardized way so nobody has to waste their time on “SpecOps” a.k.a building weird brittle CLI scripts that mush YAML about.

Arazzo has defined the one workflow format for testing tools instead of everything building their own, but it’s also being used by OpenAPI-based documentation tools to break free of being API reference documentation only, documenting complex workflows without loads of copying and pasting into Markdown documents.

I am curious to see what else the Special Interest Groups can get over the line, and excited to see what that does to the wider API ecosystem.

What do you see in the future for the OpenAPI Specification?

An increase in API design-first workflow now that the tooling has matured in all ecosystems enough for it to be quicker than not doing it.

At the same time I see a lot of improvements in OpenAPI-aware frameworks, and I’m excited to see more of that. Instead of writing a bunch of code then slapping some attributes around in the hope that they’re correct, these frameworks consider OpenAPI at its core, meaning that merely building the framework is generating OpenAPI.

If done properly I’m hopeful we’ll see a true hybrid approach, where people build things entirely API Design-first, then generate code in these OpenAPI-aware frameworks, and are able to accurately evolve it from there, getting the perks of both works without any of the downsides.

What other standards developments do you consider particularly significant for the API economy?

Currently 2% of global CO2 emissions come from the internet and associated devices, and 80% of web traffic is APIs. I think we’re in an incredible place to have a meaningful impact on global emissions by simply learning to track emissions of our APIs and reduce them through some of the Green Software Foundation’s projects. If every single API developer reading this took the free Green Software Practitioner course and invited a few colleagues to do the same, we’d be off to a great start.

Should more people get involved in developing the OpenAPI Initiative specifications and why?

Absolutely! Literally anyone can join the calls, and for a conversation about improving a YAML/JSON-based machine readable API description format they were honestly really fun.

Sometimes there are quite a few people, but sometimes there’s just the same handful. Whether you are bringing experience or fresh eyes, it’s all good stuff, and even if you just mostly listen to a few you might find you are learning, and you might find yourself sharing and contributing more than expected.

Author: Phil Sturgeon

Welcome to the next installment of our series of posts on people we consider to be heroes of the OpenAPI community. These people go above and beyond to contribute to the OpenAPI Initiative specifications, Special Interest Groups (SIG), or across the OpenAPI Initiative (OAI).

Our next Community Hero is Erik Wilde. Erik is an API industry expert and OAI Ambassador, and is responsible for the OAI tracks that have been a feature of the API events landscape in 2023 and 2024, with more to come in 2025. Erik has a background in research and academia, having held the roles of Associate Adjunct Professor and Assistant Professor at Berkley. He has contributed to many publications, patents, and standards, and worked with various industries and sectors, such as healthcare, education, finance, and government.

Erik filled us in on why he is involved in the OAI and his views on the role of standards in the industry.

What drives your interest and involvement in the OpenAPI Specification?

OpenAPI is one of the fundamental building blocks of today’s digital economy. It’s just a minor exaggeration to say that 100% of organizations today depend on OpenAPI in some place of their IT landscape to be able to do what they do.

Standards sometimes get a bad reputation as constraining things too much. And of course they do constrain things and there also are standards out there which possibly could have been designed better. But the important aspect is that standards create real value and they do so because people agree that using them is better than not using them.

OpenAPI has become the dominant standard for API descriptions and is effectively powering today’s global digital landscape. It’s thrilling to be part of that movement, and it is rewarding to try to help with improving the standard itself and improving the way how people learn about the standard and how to use it. We have ambitious goals for the OpenAPI Initiative to increase our visibility and make it easier for people to learn and adopt OpenAPI. I am optimistic that 2025 will change a fair bit how OAI is operating and how we engage with and help the global API community.

What do you consider to be your most significant personal contribution to the development of OpenAPI?

Right now it is probably the visibility and community around OpenAPI. I have been organizing OAI Tracks at various conferences for almost two years now. It’s always rewarding and interesting to see the many different contributions and ways how organizations are using OpenAPI.

OAI has an excellent technical arm that makes sure that OpenAPI remains a technically sound and well-designed specification. What we currently lack is a better connection with our community of OpenAPI users.

On the one hand we need that to make sure that more people are learning what OpenAPI is and how to use it. We also want more people to read our case studies and reports (planned for 2025!) so that they better understand what it takes to use OpenAPI well.

But on the other hand we also need more and better feedback from the community. What are the features people find most useful? What are features that seem to introduce complications? What are features that are missing? And what does the tool landscape out there actually implement, which brings us to the surprisingly difficult question to decide what “implementing OpenAPI” really means (which is a fascinating topic in itself and another major 2025 activity for OAI).

I think we need a larger base and better visibility in the community as a necessary step to better plan how to evolve the specification in a way that’s most useful for its users.

The OpenAPI Initiative is now a multi-specification organisation. How will the project change now that we are delivering more specifications to the API community?

Quite a bit of that is terminology and branding. We have a rather unfortunate name now that we’re not just managing the OpenAPI specification. We’ll be able to work with it, but we need to reassess our branding and things like our information architecture in general.

Our website is currently undergoing a major analysis and redesign and hopefully we will end this year with a prettier, easier navigable, and easier manageable website. One part of it is just improving things that we’ve known for a while, but taking the multi-specification aspect into account is one of the major reasons for the redesign.

What’s great is that our two new specifications are fitting into rather specific and easily explainable gaps. This means that our story of how we support the API landscape becomes more complete and overall a more convincing story. It also means that we can tell better stories of how tools and tool chains can be used because there are interoperable descriptions of various aspects throughout the API lifecycle.

In the end, being a multi-specification organization has increased the potential of OAI as a unique provider of solutions in the API space. But it also has made it a bit more challenging for us to tell our story and the story of our specifications. What do you see in the future for the OpenAPI Specification?

One of the important tasks going forward is to better understand if and how could be improved to better support AI scenarios. It might be as simple as adding some guidance around API design and how to best write the OpenAPI description for AI consumers. This is particularly interesting for AI agents which probably would want to discover higher-level information on how to use an API, for example in an Arazzo workflow description.

But we may also see that AI scenarios are requiring updates to OpenAPI, to other OAI specifications, or maybe will need entirely new specifications. We’re only at the beginning of understanding the potential and impact of AI scenarios, but I am sure that a year from now we will have a better idea about how to make OpenAPI more AI-friendly.

Personally, I think the current version has proven to provide enough value for us to invest more into explaining that value and making it easier to realize. It’s not OAI’s goal to turn into an API consulting firm, but given our unique position in the API landscape we can provide trainings, case studies, and reports with more authority than most other entities out there, and it would help our users if we did more of that.

What other standards developments do you consider particularly significant for the API economy?

First and foremost our “sister specifications” that are also part of the Linux Foundation have to be mentioned: AsyncAPI and GraphQL. And then there’s of course gRPC which is not part of the Linux Foundation but still can be considered an open standard. So these are the big ones complementing OpenAPI when it comes to providing open and established technologies for various API styles.

When it comes to OpenAPI itself then of course we have standards like JSON Schema, OpenID, and OpenID Connect (OIC), which are very central to using OpenAPI APIs and need to be treated as an almost integral part of OpenAPI by now.

What we may also see is some variant of a catalog format, where it is possible to advertise API catalogs and to describe APIs in those catalogs with machine-readable API descriptions and other metadata that may be helpful to work with the API. Since we do see more and more scenarios where scaling the API practices is one of the challenges, we may see such a catalog format emerging as a way to more easily share APIs.

Should more people get involved in developing the OpenAPI Initiative specifications and why?

Yes, it would be great to see more people getting involved with OAI. We want to play our part by creating more useful content going forward, in particular in terms of training, case studies, and reports. These things will help OpenAPI users, but the more we can create these based on feedback, the more likely we will create the ones that have the most impact.

In my mind, APIs still are too often treated as a mere side-effect of having an IT landscape where components need to be connected. Of course we need APIs on this very basic level, but in many organizations there is a lot of unrealized potential because APIs are not managed strategically. We still need to be better at telling the story of API representing business capabilities, the option value that they bring to an organization, and the steps it takes to create the right APIs and to create them the right way.

We’re only getting started with Getting APIs to Work at OAI, and given that we have big plans for 2025 this is the ideal time to join the movement, start engaging with OAI, and help us to better understand how we can better help you and the API community in general!

Author: Erik Wilde