Craft the OAS Guiding Principles

[DavidBiesack]

There are some high level goals for OAI/OAS:

1. The goal of the OAI specification is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, Swagger removes the guesswork in calling the service.2

However, these goals do not necessarily map to lower level decision criteria when looking at issues/proposals/pull requests. How does OAI/TDC resolve two competing and conflicting proposals which both satisfy the above goals?

Examples of questions/proposal in need of guiding principles:

1. "If OpenAPI wants to be agnostic about design-first vs code-first, then the specification has to be able to adequately describe real world APIs. I don't think any decisions about inclusion in the specification should be determined by how easy or hard it is for a tool to implement. That is a problem that can be solved elsewhere, and if tool authors don't want to deal with it, then let them implement workarounds. By omitting something like this from the spec entirely you just force the problem on the users." Support for Either #57 comment.
2. To that I would add the design to capture HATEOS Allow documenting HATEOAS APIs (pathless operation / interface / URI class / operation type) #577 so we can wean clients from RPC style tightly coupled clients/servers
3. To what extent should OAS be constrained to JSON Schema and other syntactic notation, vs. higher level abstractions to express things like schema inheritance) Adding merge construct #674 comment Group multiple parameter definitions for better maintainability Overlay-Specification#34 comment

I suggested drafting a set of Guiding Principles which can be used to concretely evaluate proposals.

For some examples of Guiding Principles to consider:

1. to what degree does tooling support (Swagger UI, Swagger Editor, Swagger codegen and hundreds/thousands of other tools) impact specification decisions?
2. To what degree to we rely on the crutch/claim "tooling can improving the experience"
3. How much do we weigh the ability to capture RESTful designs (such as HATEOAS) first and foremost, vs. toolability?
4. Convention over configuration. (Does a path parameter really, really have to have a required, explicit required: true?)
5. Does a lowest common denominator (such as target language/library etc.) skew OAS design choices?
6. How highly do we value making OAS documents readable/understandable/editable by humans?
7. How extensible is OAS both through structural decisions (not just x- specification extensions) Support for multiple request/response models based on headers #146 is the poster child...
8. Evolvability, maintainability of specifications
9. Removing ambiguity, misinterpretation
10. Conciseness
    etc

We may not be able to get purely objective criteria, but then again, principles are usually more subjective than objective.

[timburks]

I think this is worth more discussion.

There's a tension between "meeting developers where they are" and making value judgements and promoting good practices. One feature of OpenAPI that will help it and the API ecosystem grow is abstraction. By allowing implementation details to be hidden by generated code or other adaptors, OpenAPI can make it easier for more people to be API developers and users. But this requires high-quality tooling, and adding complexity to the spec to include more stakeholders makes that more difficult.

There is a purpose statement on the home page of the Open API Initiative: "Open API Initiative (OAI) is focused on creating, evolving, and promoting a vendor neutral API Description Format based on the Swagger Specification." But the value of that isn't directly stated. The best justification that I could find is on the About page: "Creating an open description format for API services that is vendor neutral, portable and open is critical to accelerating the vision of a truly connected world." Based on that, "meeting developers where they are" is true to the Open API mission, but as I hinted above, I don't think that's the same as making it possible for more people to easily create and use APIs, which would include picking and promoting best practices that can be well-supported by automation and accessible to future users.

[handrews]

I've transferred the comments to the now-more-appropriate venue of

• What principles can we define to help identify priorities? sig-moonwalk#13

so I'm going to close this out.