中文
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.
The Challenges
In modern engineering organizations, documentation is a product of collaboration among several teams:
- The AppDev team developing the APIs is responsible for the API reference documentation.
- The DocOps team formulates the business value of the APIs.
- The DevOps and NetOps teams publish the APIs and are responsible for enforcing access policies, information that’s critical to the API consumer and hence important to include in the documentation.
- The Marketing team is responsible for attracting prospective customers.
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 Solution: NGINX Controller
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.
- With NGINX Controller, the process of publishing an API and its documentation is greatly simplified. With a centralized publishing process for both the APIs and the documentation, Controller eases the operational complexity of publishing.
-
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.
Developer Portal configuration management - Combined with the unified publish process, Controller’s declarative‑style API simplifies API and documentation maintenance by integrating it into CI/CD pipelines.
-
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.
API reference documentation on the Developer Portal - With Controller, API documentation can be continuously improved without affecting the APIs on the gateway.
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.
