Structuring the thoughts around membership value proposition

[dret]

Thinking about the potential "OAI workshops" in Paris, one thought I had was to have reduced member prices for these workshops. The it occurred to me that since most members are tool providers, they're not really going to take these workshops. Which then made me think about our current and target "membership demographic". We can look at the current state:

• Tool makers: This is the majority of current members. That makes sense because that's how the current model works, it's mostly about showing support for the spec and that's almost all that these members want. We could do better with membership badges and "member of the month" postings, but that's a different discussion.

• Power users: We have some members who use OpenAPI a lot but aren't OpenAPI tool makers. They, too, want to show support for the spec because it is an important part of how they generate value and revenue. But they, too, don't need much support from us in terms of "getting better at OpenAPI".

• OpenAPI adopters: What if we target at least some and maybe most of the membership value proposition thoughts around organizations that want to get serious with OpenAPI? Maybe they want to build their own ecosystem around OpenAPI or they want to treat APIs more strategically internally. We could help those a lot with better understanding what to do and with, for example, workshops and other educational formats.

I would be curious to hear what people think. Do these three groups make sense? Should we start looking beyond the experts as our membership focus and explicitly target those who want to start using OpenAPI more strategically and wonder how to best do that?

[dret]

As one example of how we could start creating value for the "OpenAPI adopters", here are some ideas around one possible way how we could approach the workshops in Paris:

OAI Workshops at API Days Paris

This is about organizing several full-day "OAI Masterclasses" at API Days Paris. The exact number and format are to be discussed. The current thinking is as follows:

• Planning, marketing, and management will be jointly done by API Days and OAI.

• The masterclasses will be paid, maybe something in the $800 range. Members get significant discounts. Organizations registering more than three people also get discounts.

• All classes start with a shared "OAI OpenAPI Fundamentals" module that's 90-120min in length. It provides a general overview of the why, what, and how of OpenAPI without going into any details. The "OAI OpenAPI Fundamentals" module gives people the "OAI OpenAPI Fundamentals" certificate which is issued to participants as a digital and easily shareable badge.

• After the introductory "OpenAPI Fundamentals" module participants split up into smaller classes. The current thinking is to have (some of) the following more advanced modules, which will all take up the rest of the day. All these advanced courses will issue OAI certificates as well.

  • "OAI Advanced OpenAPI" which is a deep dive into how OpenAPI works. This one could use Chris Wood's materials and [email protected] has indicated interest to teach this module in Paris.

  • "OAI API Strategy & Governance" looks at the bigger picture of how to align business and tech, how to help with API practices, and how to use APIs in a variety of ways to create value for organizations, for example through monetization.

  • "OAI API Product Management" looks at what to do as an API product manager. It focuses on looking at API as products, how to create and manage these products, and what goes into making these products as successful as possible.

  • "OAI OpenAPI for Developers" looks at how OpenAPI can help with the API lifecycle, and then includes a number of deep dives into tooling. Possible tool ideas include linting, mocking, documentation, testing, fuzzing, and possibly others.

• Ideally the content and certificates are or will be made available as remote trainings on the API days learning platform apimasters.io. The goal is to establish OAI certificates as something of value and durability in the community.

[handrews]

@dret

OpenAPI adopters: What if we target at least some and maybe most of the membership value proposition thoughts around organizations that want to get serious with OpenAPI? Maybe they want to build their own ecosystem around OpenAPI or they want to treat APIs more strategically internally. We could help those a lot with better understanding what to do and with, for example, workshops and other educational formats.

I agree that this is the key area for expansion.

Something that I see is that while smaller organizations tend to just pick a set of tools and go with it, larger organizations that are concerned with broader interoperability are somewhat baffled by the inconsistencies in the ecosystem. Ideally, we kind of need a "can I use..." site that cross-references features with different tools and ecosystems to help navigate things. Even something as simple as "can I use 3.1 at all, or is there a tool I need somewhere that only supports 3.0?"

In the absence of such a site, maybe there is value to offer in aligning potential-member needs with what's available in the ecosystem, and (for us) helping to get a more clear view of where the gaps are and what, if anything, we can do to fill them (which would then feed back into member value for whichever member(s) are blocked on those gaps.

This could also really help our Moonwalk story and planning, as we want to avoid the interoperability problems that currently plague the tooling landscape. If Moonwalk is to be AI-oriented, we really can't afford interoperability problems as it will be even less clear who is trying to do what with which tools.

[lornajane]

I have been thinking along the same lines as @handrews in terms of doing office hours for both practitioners and tooling vendors. The "right" people to have in the room aren't always the BGB voting reps, but more like a wider tech audience from those companies. The weak point as I see it is having TSC or SIG leads available for those sorts of sessions as most of us have jobs already (and I don't think we should assume that if you're excited about specifications and standards work, you're also excited about doing technical communication and crowd management!)

[AndrewWalsh]

Does anyone here think that automated generation of OpenAPI specs of any version (not 2.0, or 3.0, but above), would help catalyse momentum towards OpenAPI? Thus lend more funding to the initiative given the value proposition. Most APIs are undocumented. Generally people use API Platforms to get around this problem, the result is (in my humble experience at every company I have worked for) incredibly poor to an extreme. They are no longer necessary with Scalar and other tools. There are of course well documented APIs, like Stripe, who seldom raise issues I imagine.

Just a thought.

[handrews]

@AndrewWalsh auto-generated in what sense? There are plenty of tools that generate OpenAPI from code, so I assume you're talking about inspecting runtime behavior?

[lornajane]

The thing about starting from anything that isn't OpenAPI, is that all those other contexts use only a part of the picture. So you end up with docs built from only what you could get from the code, or API traffic. That's totally fine if it fits your needs, but it misses a lot of the value of OpenAPI in my opinion.

[handrews]

@AndrewWalsh the problem with inspecting things on the wire is that you'll accumulate a set of things that the API does, but unless you can guarantee that you will observe every possible usage, you might leave out important things and provide a misleading description. And if you can guarantee that you will observe everything, then something already knows the full API description and it would be better to work from that than observed runtime behavior. At least that's my sense of it - there could be limited "something is better than nothing" cases where it would be useful, but the potential for confusion is very high.

[swaldron58]

There is a group missing or we need to expand the definition of OpenAPI adopters. I expect the vast majority of developers using the OAS is not necessarily aware of it. They are indirect users based on whatever tool or tools they are using. If they are currently writing JSON or other schemas directly, how many would opt to write a description in YAML instead of JSON, sans tools versus adopting the OAS as part of moving to a productivity tool? At the very least we need to consider OpenAPI indirect adapters or maybe causal adapters. I think in most of these cases it is not the developer we need to influence but the decision makers. Who is pushing and financing an effort to upgrade API development and delivery would be the target. In my last position that was me. I had a team of 100 architects who cat herded 3000 developers. I sent many of them to conferences to keep current but any change of a direction like following the OAS and how we would approach that (tooling) was based on full analysis and business case showing the potential ROI. Which I did do, won over the CFO and proceeded.

I think @lornajane touched on this. These are great proposals on how to adopt OpenAPI specs but not why. I still think we need to get some help to sort out the why, the audience we need to target and the how do we reach them. Pushing forward some education is great and I don’t want to come across as we should do nothing until we get it all planned. However we can’t lose sight that future OpenAPI adoption and hence funding will be dependent on getting a message to a very broad audience and especially those that make decisions. They won’t be the ones sitting in the class.

On a related note. Some of the discussion seems to indicate OpenAPI would be providing a master class for a fee. My understanding is OpenAPI would provide educational material as open source. Work with others for fee based education as that is not something we, OpenAPI, would want to take on nor be in competition with education providers. I’m not sure if the intent is we would invite LF to come in and set up a class or someone else. We did talk about fee based certification but that also was intended for others to perform according to criteria OpenAPI defines. We would like to see some sort of revenue sharing arrangement for the certification. That may be as simple at someone performs the certification process for a fee that they retain. OpenAPI issues the certification for our own fee. The point being that while we need a kick in the pants to get moving on this, I have my doubts how much we can get our act together before December.

[dret]

On 2024-06-25 22:02, Stu Waldron wrote: I think @lornajane <https://github.com/lornajane> touched on this. These are great proposals on how to adopt OpenAPI specs but not why. I still think we need to get some help to sort out the why, the audience we need to target and the how do we reach them. Pushing forward some education is great and I don’t want to come across as we should do nothing until we get it all planned. However we can’t lose sight that future OpenAPI adoption and hence funding will be dependent on getting a message to a very broad audience and especially those that make decisions. They won’t be the ones sitting in the class.

I like that a lot. There are some clear and clearly different groups of people to address, some of which we're currently not targeting at all. - Developers: We are, but we could be a bit more opinionated in terms of going "API first", i.e. in terms of making the case that for a successful API it will help to first think about its consumers and only afterwards about the implementation. Or we could call it "outside-in" which may be an easier sell? I don't mind that much but it is a focus we could present more clearly. - Product Owners: If you go beyond "API products" and look at "how to digitally enable *any* product", OpenAPI is front and center. Again, not something we say very clearly right now but we could. - Architects and Strategists: Treating APIs as a strategic asset and not just a digital byproduct is still more the exception than the norm. This is a more complex story to convey, but also one that can unlock a lot of potential in a lot of organizations. Good stories for this start with Amazon in 2002 and I am confident we could find them on a regular basis. For example, here's one from one of our members: https://www.youtube.com/watch?v=BCPD5NwQ7_M

[swaldron58]

This may go under the Product Owners but would add the CFO as a target. I think a compelling business case can be made based on opportunities for labor reduction in the delivery and consumption of APIs. The latter is a target rich environment often neglected. Likely several of our members have their own marketing material defining productivity and quality improvements. We can add the technical argument how those level could increase nX if our specs were widely incorporated. The goal is to show any company they can not afford not to support the OpenAPI effort and to drive adoption.
For most organizations, defensible (data driven) arguments with defined check points for cost take out or increased revenue win over any technical argument. This would be new territory for a standards body to project quantitative financial results from adoption but worth a look.

[dret]

I am a bit torn on this one, @swaldron58. I do agree that cost savings are one possible argument and that therefore CFOs could be targets. On the other hand, I have found these conversations to be more difficult and less productive that those that are more focusing on strategy and potential. APIs as cost-saving is not something we should ignore, but in my mind we might be more convincing and unlock more potential if we (at least initially) focus on them as strategic enablers. They decrease time-to-market, support innovation, allow more experimentation, enable new channels, power partner models, and do many more things that are attractive from a strategy point of view.
Thanks for bringing up this point, @swaldron58. It certainly helps us to have a more complete picture. What we want to focus on will be an interesting discussion. If anybody is looking for data points: For a number of years now I have started looking at the usual suspects such as McKinsey, HBR, Deloitte and so forth. They all have published materials looking at both points, because I guess they have the exact same goals: Supporting arguments that either are looking at the cost-cutting angle or at the strategy angle. There are of course overlaps, but in the end making one argument or the other do end up being relatively different stories.

[dret]

Thinking a bit more about that line of "API value", here's the part that oftentimes is a bit of a hurdle: In order to get to the cost-saving aspects, it oftentimes takes some initial investment and that's more than just putting some kind of API infrastructure (such as an API gateway) in place. You also need to make sure people are creating the right APIs, you have to explain and educate, you have to build a platform as supporting infrastructure, and so forth. When orgs only want to do the "minimal investment" because they are going for the cost-saving bit, I've seen them doing all kinds of things wrong and then not seeing the ROI they were hoping for and being disappointed. And of course this does not need to happen, but I've seen it happen frequently and that would be an important things to keep in mind if we want to pitch the cost-saving aspect.

[handrews]

@dret I think the most interesting cost-savings argument to make is also the most difficult one, but one we could potentially work on making more straightforward. Having an OpenAPI Description gives you a more direct way to communicate and manage API changes. We've talked about lifecycle additions to the spec off and on but it's never quite gotten traction. There are also things we could work on in terms of coming up with guidance on how to manage API changes and communicate them in the OAD.

But this is a non-trivial amount of work. It also has the initial investment problem you mention- what we'd need to do is tie the savings to the initial investment clearly enough. There's possibly something here to think about in terms of incremental adoption- many companies start with OpenAPI just for the human-readable documentation.

Finally, I've been starting to think that we don't give enough attention to the code-first use cases. I prefer description-first, and we mostly talk about people writing descriptions of existing APIs while we talk about the spec. But there are a lot of code-first shops out there, and we shouldn't ignore them.

[swaldron58]

@dret , On the comment "I have found these conversations (CFO) to be more difficult and less productive that those that are more focusing on strategy and potential.", I have found my attempts to argue for change based on strategy and potential to often fail. Over the decades I have been in innumerable C level meetings at airlines, online travel agencies, travel agencies, hotel, rail, banks, governments, and more. The common thread for all of these is they are not "IT" companies. They use IT, including APIs, as an end to means. The better ones dedicated at least 4% of their annual budget to IT, but often less. The leaders look at the IT department as a cost center. The product teams as a profit center. The often winner in any debate on where the spend should go was the profit center for fairly obvious reasons. When I, as a tech consultant or leader of the IT department, came armed with strategy and potential, well it was like bringing a knife to a gun fight. When I came with measurable steps for cost takeout, often it was the financial department that backed me up. The products teams where known to habitual liars. Always promising far more than they ever delivered and most times their claimed success was unmeasurable. This anecdotal description is just to point out most leadership, even tech leadership, can not grasp what is obvious to you, me, and everyone involved in OpenAPI when we talk about our strategy. But they will grasp and relate to issues like shortage of IT labor and growing costs. They don’t care about the technology per se, just basic arguments like more automation means less labor and we can get to more automation by supporting standards. My goal being in addition to our messaging for technical teams, we reach out to leaders of non-tech companies that this is how they stretch the scanty 4% they spend on IT.