Category Archives for "Uncategorized"

How API-First Design Helped Win a $22m Enterprise Deal

The background…

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.

Hello world, our mission is to perfect the API Developer Portal

ReDoc was born out of frustration with rendering my OpenAPI definitions for API reference docs.

Developer documentation is very important to a developer’s experience.

And that documentation extends beyond the API reference.

An API Developer Portal extends beyond mere documentation too.

Our mission is to perfect the API Developer Portal, one big factor of the developer experience. The other factors will likely be your API design, implementation, uptime, and speed.

Please comment or contact us to let us know about excellent and terrible experiences you’ve had with developer portals. There is plenty of learning to do from both ends of the spectrum.

To read or learn more, check out our article on Medium about API Docs.

Or stay tuned by requesting an invite.