Over a million developers have joined DZone.

Are API Docs and Definition Formats a Single Thing or Separate?

Do you see API Documentation and Description formats as a single thing or multiple things? It's an intriguing question that Kin Lane explores in this post.

· Integration Zone

Build APIs from SQL and NoSQL or Salesforce data sources in seconds. Read the Creating REST APIs white paper, brought to you in partnership with CA Technologies.

I was reading a virtual panel: document and description formats for web APIs and thought the conversation was very productive when it came to helping bring the world of API documentation and definitions into better focus. I encounter daily reminders that folks do not see the many dimensions of API definitions, and the role they play in almost every stop along the life cycle. This virtual panel helps move this discussion forward for me, providing some clarification for when it comes to the separation between API definitions and API documentation.

One of the questions asked of the panels was, "do you see API Documentation and Description formats as a single thing or multiple things?" I found Zdenek Nemec (@zdne)'s answer to be a great introduction for folks when it comes to understanding the importance of this separation:

There are definitely two different things. But truth be told, the initial incentive for the use API description formats was definitely the vision of API documentation without much work. However, the tide is turning as more and more people are discovering the benefits of the upfront design, API contracts, and quick prototyping.

Many people still see machine readable definitions as purely something that drives API documentation. OpenAPI Specs are just for deploying Swagger UI and API Blueprint is just for using Apiary. In reality, the why and the how you are doing API definitions is much, much deeper. As Z from Apiary points out, it is key to the API design and prototyping process, and critical to establishing the API contract.

Realizing that crafting machine readable API definitions is not just about API documentation but that it is also essential to establishing a meaningful technical, business, and legal contract internally, with partners, and maybe the public, early on in this API life cycle is empowering. I would say that I didn't fully appreciate API design or understand the depth of it until I had OpenSpec providing me with a scaffolding to hang things on.

Anyways, it is a great conversation from some very smart folks over at InfoQ. I recommend heading over and spending time absorbing it. I'm leaving it open for a week and rereading it until it all sinks in.

The Integration Zone is brought to you in partnership with CA Technologies.  Use CA Live API Creator to quickly create complete application backends, with secure APIs and robust application logic, in an easy to use interface.

Topics:
integration ,api docs ,definition formats ,open api

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 }}