Over a million developers have joined DZone.

Making the OpenAPI Contract Friendlier for Developers and Business Stakeholders

DZone 's Guide to

Making the OpenAPI Contract Friendlier for Developers and Business Stakeholders

OpenAPI is working to make the contract used by API consumers friendlier for both stakeholders and developers. Let's see why and how that is.

· Integration Zone ·
Free Resource

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.

There is nothing in a YAML OpenAPI definition that business users won't be able to understand. OpenAPIs aren't any more boring than a Word document or Spreadsheet. If you are a stakeholder in the service, you should be able to read, understand, and engage with the OpenAPI contract. If we teach people to be afraid of the OpenAPI definitions, we are repeating the past and maintaining the canyon that can exist between business and IT/Developer groups. If you are in the business of burying the OpenAPI definition, I'm guessing you don't understand the portable API lifecycle potential of this API contract and simply see it as a configuration, documentation, or another technical artifact. Either that or you are just in the business of maintaining control and power by being the gatekeeper for the API contract, similar to how we see database people defending their domain.

Please do not devalue or hide away the OpenAPI contract. It isn't your secret sauce, it isn't boring, and it isn't too technical. It is the contract for how a service will work that will speak to businesses and technical groups. It is the contract that all the services and tools you will use along the API lifecycle will understand. It is fine to have the OpenAPI right behind the scenes, but always provide a button, link, or another way to quickly see the latest version, and definitely, do not scare people away or devalue it when you are talking. If you are doing APIs, you should be encouraging and investing in everyone being able to have a conversation about the API contract behind any service you are putting forward.

integration ,openapi ,contract ,api ,developers ,business

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}