Within the last year, Zuora has moved to REST for all customer-facing APIs. See Scott’s great post to learn more about that shift. In late 2016 we launched the Zuora Developer Center as a central location for Zuora developer resources. An essential part of the Zuora Developer Center is the new API Reference that we built.
Challenges for API Documentation
Before the API Reference, existing APIs were designed using a bottom-up approach, with documentation created after the code had been written. This meant there was a danger of divergence between the functionality of the API and the documentation.
In addition, documentation for the APIs was scattered through the Zuora Knowledge Center. It was sometimes difficult for developers to find relevant documentation.
Furthermore, the API documentation was in a human readable form, using plain text and tables, not in a machine readable form. This meant that developers could not integrate the documentation into their development environments.
API Reference Solution
To improve this situation, we formed a new strategy: Zuora developers would take a top-down approach to designing APIs, with documentation-friendly specifications written first. These specifications would be used to generate a single, comprehensive portal for API documentation.
We decided to standardize on the OpenAPI Specification, which is also known as the Swagger Specification.
Swagger is a popular industry choice for designing and describing REST APIs, with a rich ecosystem of developer tools and an active community.
Zuora developers can design APIs in Swagger format before writing code. Swagger is easy to write because we can write it in YAML, and easy to collaboratively create API documentation across teams because of SwaggerHub. This helps to support the microservice architecture that Zuora is driving towards. Another nifty side-effect is that Swagger specifications can be directly used by developers to build integrations with Zuora.
Also, there are many systems that can automatically render Swagger specifications as customer-facing documentation. This is a big improvement over the old way of writing and publishing API documentation; if the API was built according to the Swagger specification, the documentation is sure to be correct.
Building the API Reference
We first had to convert all our existing Knowledge Center API documentation into Swagger specifications and validate it. This was a semi-automatic process. After that, we follow the top-down approach to API development, with Swagger specifications written before coding begins.
We had to decide which system to use to render the Swagger specifications. ReDoc is our choice. Many of our REST APIs were implemented to manipulate SOAP objects, with several layers of nested objects. ReDoc can show nested request and response objects really clearly. ReDoc also provides a three-panel view with support for Markdown and fancy multi-language code samples.
In terms of the number of API endpoints in a single reference, we are one of the largest users of ReDoc. We have been working closely with the ReDoc developers to optimize the performance and features to make our API Reference as easy to use as possible.
Zuora is now developing new APIs using a Swagger-first approach. We are constantly improving the maintainability and quality of our Swagger specifications.
We have put together our own Swagger Guidelines as a reference on how to write a valid Swagger file and ensure consistency within Zuora. A simple but complete Swagger template is also a good start for API developers to write Swagger specifications.
We fully understand the importance of an API changelog to customers, and we are working on this to make the changelog public soon.
We are also working with the ReDoc developers to find a scalable way to integrate future APIs into our already-large API reference.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.