API, documentation and client libraries

API, documentation and client libraries

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:

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, …

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.

Leave a Reply