Over a million developers have joined DZone.

Cutting Through the Smoke & Mirrors of IT Discussions Using API Definitions

In about 75% of the situations, IT, and developer representatives are nice, or rather they are tight-lipped, relying on a myriad of smoke & mirrors to defend their dark arts.

· Integration Zone

Learn how API management supports better integration in Achieving Enterprise Agility with Microservices and API Management, brought to you in partnership with 3scale

I get brought into a lot of API discussions with IT departments from companies, institutions, and government agencies, which are often coordinated by business groups who are interested in better meeting their goals using APIs. This is often an immediately charged conversation, with IT coming to their table with a whole array of baggage. 

In about 75% of the situations, IT, and developer representatives are nice, or rather they are tight-lipped, relying on a myriad of smoke & mirrors to defend their dark arts. Let me stop for a moment, and put out there that I was IT director from 1998 through 2010. I'm not saying IT are bad people, but there are a wide variety of ways we slow, obfuscate, and distort the conversation to be in our favor -- takes one to know one. I wouldn't say that I was 100% honest in my approach to being an IT leader, but I tried my hardest to keep things as transparent as I possibly could.

Anyways, in a couple of the  IT discussions I've had lately, there was an OpenAPI Spec available to define the resources that were on the table, and in a handful of other conversation there were not. Keep in mind that most of these scenarios are with a more traditional version of IT, not with startup technology groups (a whole different beast). As I step back, I am taking notice of the harmonizing effect that an API definition can have, in keeping conversations focused, productive, and moving forward toward a common goal.

In the conversations without an OpenAPI Spec, back-end systems and legacy processes dominated the discussion, even though we are all on a conference call to discuss an external, partner, and public facing API. In the discussions where an OpenAPI Spec was present, we focused on exactly which resources were needed (nothing more), and the details (params, responses, etc) that were needed by all consumers--essentially providing us with a scaffolding for the discussion, that kept things moving forward, and not bogged down in legacy sludge. 

Backend focused discussions always seemed to get slowed down by what was, and what is. The API definition focused conversations seemed to focus on what was needed, using a common language that everyone at the table understood. The presence of an OpenAPI Spec seemed to cut through the smoke & mirrors, which I think often alienates many of the business users. I find having three versions of an OpenAPI Spec and APIs.json file present: 1) simple outline 2) YAML and 3) JSON, was also something that significantly improved discussions, keeping conversations focused while also making them as inclusive as possible.

I think people will always bring their baggage to these discussions, but I'm liking the harmonization effects API definitions like OpenAPI Spec, API Blueprint, Postman, and APIs.json are having in these conversations. I'm hopeful that these API definitions can continue providing bridges between business and IT groups, helping close a canyon that has existed for decades.

Unleash the power of your APIs with future-proof API management - Create your account and start your free trial today, brought to you in partnership with 3scale.

Topics:
api ,definition ,spec

Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

SEE AN EXAMPLE
Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
Subscribe

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

{{ parent.tldr }}

{{ parent.urlSource.name }}