By the time ReDoc was released in 2015, I was more comfortable with the OpenAPI (fka Swagger) specification. We had a system to structure our API definitions into three folders: code_samples, definitions, and paths. I could quickly define a new API, and was getting comfortable doing so… At Rebilly, a great opportunity arose to work with a larger enterprise. However, they said it would be a lengthy integration process as they use a 3rd party ERP, and rely on the 3rd party for integrations. We waited. And waited.
I prepared an integration guide, specifically for them, mapping their terminology into ours, and preparing various sequences to outline the main use cases they would be implementing. After discussing the guide with our customer, it became clear that the already lengthy integration might never actually be completed.
Transition to API-Design First
We needed a different approach: a different API. It needed to be more familiar to the 3rd party, but would still allow us to deliver on our key promises. We decided to craft a partner-specific API. Instead of building the API first, we decided to co-design it with our partner.
Step 1. Shared Github Repo
And to do that, we used a private Github repository, with our familiar 3-folder structure.
Step 2. Setup CI to Build Docs
We hooked up Jenkins continuous integration server to build the ReDoc rendered API docs for both the working branches (we called these previews) and the mainline branch (our master). Then, we created an initial proposal for the API.
Step 3. Collaborate in the docs (not outside the docs)
Business analysts at our client and the 3rd party were able to read the rendered API Reference docs, and ask further questions. We answered their questions by adjusting the API definitions, and then sharing the new preview version of the API reference docs. We ended up with flowcharts, and free-formed documentation inside of our definition — not a typical definition. Ultimately, they became convinced and the tables were turned on us. Suddenly, they needed the API, as fast as possible.
Step 4. Build
Thankfully, by the time we began development, we knew we would be building something they could integrate more quickly — so we were confident in making that investment ourselves. Because we had elaborated our API Docs before we built our API, our team was also really clear on what they had to build, and it boosted the development speed.
Step 5. Profit
Since we were only getting paid once the API was in-use, this sped up the time to get cash. Our development finished quickly, and the integration was ultimately a success.
Using API Docs in API-Design First Approach Yields Better Results
API Docs played a big part in the API-First Design methodology, because many of the stakeholders were non-technical or just not familiar with Swagger at that time. Presenting visually appealing API draft docs, made Rebilly seem professional and competent. And it allowed for more participation in collaboration. The docs were easier to read. Looking back on that day, ReDoc helped Rebilly win a $22m enterprise deal.