We have an UPDATED blog post on this topic!
After 7 years of improving our code base and answering diligently questions on our mailing list , we have decided that one of the main focus of our upcoming 0.20 release should be focused around API and documentation. We have worked on a series of initiatives, all related to these particular topics:
APIs
On the API side, our effort has been mostly focused on the endpoints — HTTP/REST level API — to make sure we reach some level of consistency. So, we went through our 250+ available endpoints and re-visited things like http verb, json format, http headers, http status to make those as uniform as possible. As we were doing that work, we took a second pass at all the Swagger annotations to make sure they are aligned with the code, and therefore we end up with a Swagger doc that is as precise as it can be.
One nice side effect of doing this work, is that we are then able to rely on existing Swagger tools to start generating client code: At this point we have 3 fully generated client libraries:
- Java client
- Python client
- GO client: This came as an external contribution from the folks at Google — thanks Prem! On that side, also note the nice go command line contribution.
For other languages — e.g ruby client –, we are still using our manually generated client libraries for now but code contributions to work on the swagger codegen are welcome 😉
Documentation
On the documentation side, we have worked on the following aspects:
- We have aggregated our different docs under http://docs.killbill.io/ to make it simpler to navigate; in particular we have eliminated our older wiki pages.
- We have simplified the initial guides by removing the matrix of possible deployments options and focused on docker based deployments.
- We have reworked the flow of the documentation and went through each page to make sure they are up to date and as clear as possible. We would appreciate feedback on what is not clear or missing from these, either through PRs or simply as a comments on the mailing-list.
- We have also updated our doc with new features available in our 0.20 release
- Finally, we took a pass at the form of the docs, reworking CSS, …
UPDATE: You can see an updated version of our documentation work here.
Merging api and documentation
Finally, we have created a new api documentation. The Swagger interactive tool is still available locally under http://127.0.0.1:8080/api.html, but this doc goes deeper and provides code snippets in various languages. This is a very large endeavor, and at this point we have focused on the most important endpoints but we are still working on supporting additional languages.
We hope all this tedious work will pay off and improve our users’ experience. And again, any feedback is welcome.
