Why did we change our API documentation?

Table of Contents

A year back when we were looking out to solve the API Reference puzzle, we knew for the fact that seamless automation, scalability, and ease-of-usage were the few corner stones on which we wanted to build the new ecosystem. The market is flooded with many new age API docs tool, but getting the right tool was critical to achieve our intended goals. After careful evaluation, we finalized the tool that provided the most comprehensive solution. Identifying the tool was followed by doing a thorough proof of concept by using Prism APIs as our first test vehicle.

During the implementation phase, we faced many challenges like structuring the API entities, validating the code-samples, and designing the layout. We encountered new issues on a daily basis and then did many sync-up calls to troubleshoot the issues. In the end everything materialized and it led to the solution that not only served our purpose, but provided us with the capability to replicate the solution to the multiple product lines.

Salient features of the new API ecosystem

  • Automated the API docs process: The entire API documentation cycle has been automated and there is bare minimum manual intervention required. The tasks which used to take days can now be completed within an hour.
  • Provided scalability with ease: The new ecosystem is highly scalable and accommodating multiple product lines is not a challenge anymore.
  • Lead to less dependency across teams: Apart from the validated JSON, there is no other dependency across teams to publish APIs.
  • Generated code samples: The new ecosystem supports automatic code-generation in 12 different languages, such as Shell, Go, Java, JavaScript, Node, Obj-C, PHP, Python, Ruby, Swift, C#, and C.
  • Supported seamless migration: Migration to the new ecosystem was hardly any challenge, since all we needed was the validated JSON as an input.
  • Provided seamless publishing: Previously it used to be a daunting task that used to take few hours, now its just couple of clicks.
  • Support for Open API Specification 2.0: Provides full support for OAS 2.0.

Armed with this new way of doing things, let’s take a look at an example of how easy this is now. Last week our API Reference only referenced API v2 and API v3. Now, because of how easy it is to add references to previously-unpublished APIs, we have added the Foundation APIs! For those not familiar with it, Foundation is the time-tested Nutanix deployment tool that allows customers and partners to quickly and efficiently deploy everything from new nodes to entire clusters. For the documentation, this new streamlined approach made the publication of the Foundation APIs very simple and only took a few minutes, compared to the hours or days this would have taken before. So, where can the new Foundation API docs be found? Here you go …

Make sure to check back later for more!

© 2024 Nutanix, Inc. All rights reserved. Nutanix, the Nutanix logo and all Nutanix product, feature and service names mentioned herein are registered trademarks or trademarks of Nutanix, Inc. in the United States and other countries. Other brand names mentioned herein are for identification purposes only and may be the trademarks of their respective holder(s). This post may contain links to external websites that are not part of Nutanix.com. Nutanix does not control these sites and disclaims all responsibility for the content or accuracy of any external site. Our decision to link to an external site should not be considered an endorsement of any content on such a site. Certain information contained in this post may relate to or be based on studies, publications, surveys and other data obtained from third-party sources and our own internal estimates and research. While we believe these third-party studies, publications, surveys and other data are reliable as of the date of this post, they have not independently verified, and we make no representation as to the adequacy, fairness, accuracy, or completeness of any information obtained from third-party sources.