Making the OpenAPI Contract Friendlier for Developers and Business Stakeholders

I was in a conference session about an API design tool today, and someone asked if you could get at the OpenAPI definition behind the solution. They said yes, but also quickly said that the definition is boring and that you don’t want to be in there, you want to be in the interface. I get that service providers want you to focus on their interface, but we shouldn’t be burying or abstracting away the API contract for APIs, we should always be educating people about it and bringing it front and center in any service, tooling, or conversation.

Technology folks burying or devaluing the OpenAPI definition with business users is common, but I also see technology folks doing it to each other, reducing OpenAPI to be just another machine-readable artifact alongside other components of delivering API infrastructure today. I think this begins with people not understanding what OpenAPI is, but I think it is sustained by people’s view of what is technological magic that should remain in the hands of the wizards and what should be accessible to a wider audience. If you limit who has access and knowledge, you can usually maintain a higher level of control so they use your interface in the case of a vendor, or they come to you to develop and build an API in the case of a developer. https://goo.gl/hSRjRn #DataIntegration #ML