DZone
Integration Zone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
  • Refcardz
  • Trend Reports
  • Webinars
  • Zones
  • |
    • Agile
    • AI
    • Big Data
    • Cloud
    • Database
    • DevOps
    • Integration
    • IoT
    • Java
    • Microservices
    • Open Source
    • Performance
    • Security
    • Web Dev
DZone > Integration Zone > Cutting Through the Smoke & Mirrors of IT Discussions Using API Definitions

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.

Kin Lane user avatar by
Kin Lane
·
May. 27, 16 · Integration Zone · Opinion
Like (2)
Save
Tweet
3.99K Views

Join the DZone community and get the full member experience.

Join For Free

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.

IT API

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

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • How to Integrate Zoom in React Application?
  • What Is Sharding?
  • Chopping the Monolith
  • Portfolio Architecture Examples: Automation Collection

Comments

Integration Partner Resources

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • MVB Program
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends:

DZone.com is powered by 

AnswerHub logo