API versioning is one of those topics that divides developers into two camps: those who just know that their way is the best way, and those that are confused by the first camp and would rather pass on the whole thing. Once we set aside the bikeshedding, there are sound, sane justifications for choosing one method over another, but in a lot of cases, discussions move from theoretical to hypothetical problems instead of worrying about making things that work.
The good news for Rails developers is that adding versions to an existing application doesn’t have to be painful. If you know what to do, you can implement it and maintain it with little effort.
In this article, we’ll look at what you get by versioning your API, why you need to think really hard before deciding not to, and how to update your application to make it work.
The introduction of API-only applications in Rails 5 makes it easier than ever to write simplified apps that render JSON responses. This is terrific news for those of us who’ve spent years building up expertise in the platform, but as we already know, getting off on the right foot makes a big difference in how development proceeds. This tutorial offers a quick overview of the first steps you’ll use to get set up and coding on a typical Rails API application.
In the last article, I explained why it’s a bad idea to test your Ruby code against real API endpoints and introduced WebMock as one option for stubbing out those integrations and keeping your tests speedy and manageable even as your suite grows.
That post used a really basic example application to show how to structure your tests under a simple use case. But writing and testing distributed applications is rarely that simple, and most of the time, you’ll find yourself needing to stub whole classes of requests and handle a number of common edge cases. So using the patterns from last time as a baseline, let’s now take a look at some other practical WebMock techniques to help you use it more effectively.
I’ve recently been working on a number of projects that are built on multiple Rails applications, microservices, and data from third-party providers. I can tell you one thing for sure: when your application is flinging JSON blobs all over the place, you can’t use the same direct testing style that you would with a monolith. Do so, and you create all sorts of problems for yourself including:
- Lousy test performance due to network overhead
- Unexpected failures caused by connectivity issues, API rate limiting, and other problems
- Undesired side effects from using a real web service (possibly even in the production environment)
But the thornier problem is the lack of control you have when using live APIs for testing. Working against a real system, it becomes a real trick to exercise your code against a full range of reasonable (and unreasonable) responses, so you find yourself stuck testing a few “happy path” scenarios and perhaps any cases that might happen to throw an exception from somewhere in the stack.
As adoption of agile methodologies increases, more teams are finding user stories to be a useful tool for framing discussions with customers. By defining features using simple, clear language and emphasizing the direct benefits to end users, project teams can organize and plan development activities in a way that’s accessible to both business and technical stakeholders.
But like many other agile practices, much is lost between theory and application. The original concept that drove the invention of user stories has been obscured with increaed popularity and wider adoption. As a result, many development teams are trying to use the technique to solve problems it was never intended to address and seeing lackluster results.
Understand this: user stories are not a lightweight substitute for traditional requirements management and documentation. They’re great when used as a high level outline of project features, but they’re not a solution to every problem, and certainly not a replacement for a good specification. By following an approach that includes user stories and selected, well-maintained documentation, development teams are able to better address a wider range of needs that every project will encounter.