The Evolution of the Interswitch API Documentation
Zainab Abubakar | Software Engineer, Core Service and Integration
Last year, the Developer Relations team in Interswitch Engineering was tasked with improving the experience of developers integrating with Interswitch APIs. There were lots of bad reviews regarding our APIs ranging from the complexity of the APIs which made integration difficult, to lack of proper API documentation and support.
However, chief among the issues was the documentation and we set out to remove the stumbling block. To achieve this, we tested several platforms before arriving at a decision on which one best suited our needs and better serve our users. We also worked with internal and external developers to ensure that we tackled all existing problems and improved the overall experience of developers integrating with our APIs.
In this article, we will walk you through the evolution of our API documentation, introduce you to the new documentation platform, and describe how it addresses the issues of the previous documentation platform.
The Old Documentation Platform — DocBase
There has been a misconception over the past few years that Interswitch does not have a centralized documentation platform and instead gave out PDF documents to aid the developer’s integration with our APIs. While this was as true at some point, it had not been the case for a while now.
A few years ago, we moved our API documentation to DocBase in a bid to have all API documentation in a single place and thus improve developers’ experience. While this solved some of our documentation issues, others persisted.
Disadvantages of the old documentation platform
- Lack of proper awareness amongst developers during project launch: Developers are the primary users of API documentation and as such should be at the forefront of any awareness campaign done at project launch but this wasn’t done when DocBase was launched and that made almost everyone in the developer community unaware of the existence of our documentation platform.
- Outdated Content: There was a disconnection between API update and documentation update. Oftentimes, the documentation was not updated when improvements were made thereby making the documentation become obsolete.
- A disconnection between our external and internal developers: Any developer can attest to the fact that whenever they experience issues with integration, getting support from an internal developer gets the issue resolved faster either because the internal developer has more understanding of the API or the ability for developers to understand the issue clearly. However, this was not the case as DocBase platform was managed solely by a different team, thereby resulting in little or no interaction between our internal developers and external developers.
- Now don’t get me wrong, docBase also had its advantages such as its provision of a one-stop platform for all our APIs and a community forum page. However, as most of our external developers could attest, the disadvantages outweighed the advantages, and with that, the need to sort for improvements and create a better platform for our API documentation that addressed these disadvantages.
The New Documentation Platform — Slate
The new documentation platform was built with slate, a Ruby-based tool that generates a great-looking, three-panelled API documentation static site from a set of markdown files.
To improve our documentation, Slate was chosen for the following reasons:
- In a bid to promote open source movement, Interswitch has been adopting the use of some open source tools and our documentation platform is one of them.
- Slate’s flexibility gave us the freedom to build what we wanted without starting from scratch. For instance, we were able to transform it from its original single page three-panelled API documentation static site to a multi-page site with a homepage for all product categories.
- Slate provides out-of-the-box syntax highlighting for over 100 languages with no configuration required.
- It could be hosted in a public GitHub repository which will make it simple for other developers to make pull requests to the docs if they find typos or want to make suggestions. Interswitch Engineering has plans to make the documentation open source in the future so that developers can report issues and raise pull requests to update the documentation.
- Even though Slate offers great features, we knew that we needed to put some internal processes in place to ensure it doesn’t end up like our previous API documentation. To achieve this, the developer relations team assumed the documentation team position and also ensured that for every API built or modified and pushed to production, a corresponding API Reference must be updated on Slate and pushed to the documentation team for review.
Additional Features
The developer relations team seeks to bridge the gap between our external and internal developers to ensure that the integration process of our APIs becomes seamless. Here are some other things we’ve done to ensure that the goals come to reality:
- Developer Forum: We created a forum that will connect our internal and external developers thereby giving them a place to easily interact, make feature requests, report bugs, suggest edits on documentation, carry out beta testing, etc.
- Developer Console: The new developer console provides self-service integration, giving you the ability to access Interswitch product APIs, authentication parameters, sandbox and production keys, documentation, and seamless project management.
- Admin Dashboard: A dashboard that will be managed internally and used to manage APIs on the developer console. Requests from the developer console would also be handled seamlessly on the admin dashboard.
Conclusion
We might not be where we want to be but at Interswitch Engineering, we believe we’ve taken a bold first step in the right direction to give our developers the better and seamless integration experience they deserve.
Want to try out our APIs on the new developer console and our rebranded API documentation? Click here to get started.
