User:EEvans (WMF)/Opinions/OpenAPI

= OpenAPI Considered Harmful = From Wikipedia:"The OpenAPI Specification, previously known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services. Swagger and some other tools can generate code, documentation and test cases given an interface file."

Hot or not?
A machine readable specification would seem to offer many benefits, but how many of them are manifest? Production and consumption are oft-cited, but who among us has used a spec to generate client or server stubs, and of what value would they provide once the stub has been filled in? If you cannot either generate the specification from code, or (meaningfully) generate code from the specification, then the specification becomes a (manually maintained) duplication.

Of the benefits cited, the only compelling one is documentation.

On separation of concerns
Of the information encoded in a valid specification, some of it directly correlates to the interface, and some of it to the instance of the service implementing that interface. The former moves in lock-step with the code (it is code for all intents and purposes), but the latter is configuration. This coupling violates well established separation of concerns (you would never hard-code contact information, port numbers, or filesystem paths in application code).

This isn’t just a hypothetical concern, consider RESTBase, where the inability to maintain this separation resulted in the specification becoming the application configuration.

Making it worse
Here at the Foundation, we’ve created an extension called, and all but made it compulsory. The  structure is added on a per resource and method basis, and describes a valid request and the expected response. A script called service-checker is executed against a published specification, invokes the service using the request defined, and validates a compliant response. We use this for availability monitoring. This sounds great, but all we’ve really done is implement a bespoke way of doing integration testing; The  stanza is a DSL for writing tests, and service-checker is the test runner.

Additionally, not only is this bespoke integration testing too simplistic for anything more than the most basic of synthetic transactions, it also provides no means of parameterizing runtime values, once again requiring that we hard-code configuration into the specification.

Conclusion
OpenAPI isn’t an original idea, WSDL (for example) flashed in the pan more than 20 years ago. Unlike OpenAPI, the SOAP frameworks of the day were able to generate WSDL output, and there were none of the issues with coupling of interface and runtime values. Nonetheless, WSDL failed because there wasn’t compelling value; WSDL failed because it was a solution in search of a problem, and so is OpenAPI.

But what about documentation?
Presumably we need a DSL of some sort to document our APIs, (be that doxygen comments, markdown, wikitext, or whatever). OpenAPI YAML that is treated as nothing more than a way of formatting documentation might be a reasonable choice. This is very different though from an expectation that every service publish a complete specification (let alone ones that builds integration testing into them).