According to a survey conducted by Cloud Elements, 85% of businesses consider APIs to be fundamental to their business strategy and continued success. A strong API initiative drives business growth and enables new customer experiences while reducing time to market.
Ensuring a good developer experience is critical to a successful API strategy, so one of the main challenges for an API publisher is producing documentation that is a good representation of the API initiative. API documentation is the first and foremost factor API consumers consider when choosing an API. Whether the APIs are public, private/partner, or internal, developers invest a lot of time in learning, using, and referencing them, largely through the documentation.
Comprehensive API documentation not only helps the consumer evaluate the API, it also reduces the time to get started with consuming them. If the documentation is incomplete, unclear, or hard to use, developers are quick to switch to a competitor who offers a better experience.
In modern engineering organizations, documentation is a product of collaboration among several teams:
During the design and development phases, the API publisher has to identify the different types of content to include in the documentation to make it rich, robust and easy to consume.
Once the documentation is published, it can be challenging to keep it in sync with changes to the API itself. The docs must be updated proactively to maintain their value to the API consumer. This is made even trickier if you use different tools to publish the documentation and the API itself.
A second challenge with published documentation is versioning. In an agile world, products and their associated APIs can change quickly. Customers tend to be cautious about updating, so you must continue supporting current product versions while introducing new ones, and inform API consumers about changes. You need to implement a version‑control system for the documentation as well, and continue to maintain each version until the associated API version is deprecated.
A final challenge is to continuously improve the API documentation, enhancing its role as a market differentiator. Both the API reference documentation and material that explains the business value of the API are candidates for improvements.
All these challenges can become even harder as over time organizations end up with an array of tools and processes. Most tools today decouple publication of APIs and documentation. While API publication tools are great at keeping APIs up to date, they lack functionality for keeping the documentation in sync, forcing you to rely on other tools or manual processes. Even worse, as APIs scale, tool sprawl quickly gets out of hand and manual processes can become increasingly error prone.
The challenges faced by the API publishers can be effectively addressed by combining the publication process for APIs and documentation. Documentation updates stay in sync with product updates when you proactively make documentation a required step of the API deployment process.
As you develop APIs, NGINX Controller can import the spec and bootstrap API definitions and documentation within Controller itself. Controller supports versioning and can import the relevant information from the source control system. The publication process ensures that as you release new versions of an API to the gateway, the corresponding documentation is published to the Developer Portal.
Controller supports publication of selective APIs or routes in an API definition, and ensures that the documentation is published for only those APIs and routes that are actively deployed on the API gateways.
With an easy-to-use declarative API for automation or a GUI with a guided workflow to manage the publishing process, NGINX Controller is a great fit for organizations that adopt a design‑first API strategy.
Get started with a free 30-day trial of NGINX Controller today or contact us to discuss your use cases.
"This blog post may reference products that are no longer available and/or no longer supported. For the most current information about available F5 NGINX products and solutions, explore our NGINX product family. NGINX is now part of F5. All previous NGINX.com links will redirect to similar NGINX content on F5.com."