Apiary on API Versioning and Testing Strategies

During last week’s Heavybit Speaker Series, Stripe’s API lead Amber Feng did a presentation on API versioning.

Offered Feng, “Building APIs… requires a lot of iteration and feedback cycles. Nobody gets it perfect the first time so you’re constantly going to be changing things.”

This is absolutely true. For any API strategy to grow in an organization, there will always be a need for greater functionality, more endpoints and definitely changes along the way. But all of this leads to new challenges with versioning and documentation.

Stripe decided to solve these problems by following an aggressive versioning strategy and Amber offers details of that in her own post. Their process involves separating different layers of logic and producing API results from a central code base. This led to the evolution of a series of ‘gates’ — post-processing and pre-processing filters that adapt the API to historical versions. This means that the company can serve the exact same version to developers as they started with and will continue to serve the same version forever. They handle the versioning process internally through these gates, providing a seamless experience to developers who would not have to worry about different versions of the API.

To date, Stripe has had 65 different versions of their API, 106 endpoints and 6 API clients — all versioned through gates. These 65 API versions run in parallel and developers can run their code from 2 years ago without the need to make changes. The challenge now comes when testing these individual versions and documenting them.

Testing API Versions and Documenting Them

Apiary (a Heavybit member) works on rapid iteration of API design. We provide API Blueprint, a simple, markdown-based language to power your product portfolio, and a range of open source tools for API documentation, prototyping and testing.

In the words of my cofounder Jan, we believe that, “The lowest common denominator for all APIs is the documentation, that’s where everything begins. It starts as a simple draft of what you’re about to build, later evolving with your development to the interface others will use to implement your API. At this point, the documentation becomes the most exposed part of your work.”

Our aim is to test and debug the most exposed part of your work, making it easier to design, maintain, discover and understand. Try Apiary and let us know how we’re doing.

###

BIO: Jakub Nesetril is CEO at Apiary, and developer at heart. His passion in API Design and prototyping led him to found Apiary in 2011. His Twitter handle is @jakubnesetril.

BIO: Neha Sondhi is Product Marketing specialist at Apiary. She was a product manager for APIs before this role and loves to learn about new technology. Her Twitter handle is @NSondhi5.