Why did we change our API documentation?

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!