Standardized API Features (SAFs)

[handrews]

This is a general discussion for the concept of SAFs, as outlined in the slide deck from today's TDC call.

We will split out specific topics as needed.

[handrews]

Code generation vs AI agents

@mkistler brought up that the design requirements for AI vs code generators are quite different, and we should determine which we are targeting as (according to what he is seeing) AI is overtaking code generation.

I noted that there are many industries that are much more conservative about technological adoption, even without taking AI into account, so we might not want to write off code gen just yet. Also, while we need to focus on AI and/or code gen, we aren't dismissing the importance of interactive documentation tools either.

Let's use this thread to discuss the differences in requirements for code gen vs AI. Code gen clearly needs things to be very precise. AI, in theory, can make inferences like a human. But humans don't always make the right inferences either, so we can't just expect agents or people to manage everything from description strings. What is the right balance? Can we solve both use cases? With the same approach or different options? I do not have answers to any of these questions.

[handrews]

The multiple levels problem

We need to figure out how to handle SAFs at different scales/levels. Some work at a single levels, others work at multiple. We need to come up with a consistent way to handle this.

Current mechanisms

This is just included to show how complex and inconsistent we are right now. Not all of these things are necessarily involved in SAFs, but they all illustrate potential ways of solving these problems.

Server Objects (servers):

• Levels: OpenAPI Object, Path Item Object, Operation Object, Link Object
• Interaction: override
• Presence: always inline
• Selection: manual from list, manual variable selection

Notes:

• Unclear why always inline
• Server Variables being different from Parameters sort-of makes sense, but not entirely?

Security Requirement Objects (security)

• Levels: OpenAPI Object, Operation Object
• Interaction: override
• Presence: Security Requirement always inline, always refs Security Schem either by entry document component name or by URI reference
• Selection: complex AND/OR logic within security field and Security Requirement Object syntax

Notes:

• Unclear why Path Item level is skipped
• Auth handled by a 3rd-party might be common across multiple APIs (Arazzo level?)
• AND/OR behavior is results-oriented, rather than allowing configurations to support each other
• Unclear why Security Schemes are never inline, although perhaps just because there is no clear use case

Parameter Objects (parameters)

• Levels: Path Item Object, Operation Object
• Interaction: union with individual overrides (but duplicates within a level are forbidden)
• Presence: inline or by URI reference
• Selection: automatic

Notes:

• OpenAPI Object level has been requested in the past
• In theory, could vary by Request Body Object but unclear if there's a solid use case (never requested?)
• While some headers can appear on either requests or responses, in: header Parameter Objects cannot be used as Header Objects
• Interesting that request headers appear at different levels than the single response header level

Header Objects (headers)

• Levels: Response Object, Encoding Object
• Interaction: n/a
• Presence: inline or by URI reference
• Selection: automatic

Notes:

• Some of these could really use a Path Item level, at least
• Encoding Object use case is more like request headers than response? Maybe? It should all be the same anyway

Further thoughts

Connection by component name allows for different use cases than URI referencing. Both seem useful, but unclear how intentional this was.

Lots of things could benefit from other levels than just SAFs.

[handrews]

Getting implementor buy-in

One of the reasons for developing the SAF concept is to highlight that this is a major expansion of the scope of the OAS into areas we have largely ignored up to this point. And one that will require additional tool development work for each feature. To make any of this successful, we need to make sure whatever we add will actually get implemented.

Our existing SAF-ish things are cookies (which no one was thinking about in these terms, and doesn't really cover the feature as you can't describe the whole cycle, only Cookie request header inputs) and "security" (which is known to be an area where tool developers often punt with some sort of plug-in interface, if they even offer that).

• How can we figure out what the tool developer community would want to implement? We know better security support is considered important, but what about things like rate limiting or sunset/depreaction?
• How can we figure out how much the tool developer community can absorb in a 3.3?
• Can we get any tool developers (particularly commercial ones) to work on implementations to help us figure out if/when we're asking too much?