Paul Hammant's Blog: Servirtium use in a client and supplier co-development

My last US consulting mission before moving back to the UK was to an airline ($70B market cap) making a UI for services provided by another air-industry infrastructure/services vendor ($30B market cap). The vendor intended to sell those services to other airlines. The airline in question was the first. Development was behind schedule and liaison between the two companies tense. I was contracted to the airline and they took me to the vendor’s offices to talk about how other companies dealt with large co-developed systems, and how they could cut through the delays.

I made a bunch of recommendations to the joint initiative, but the one that is pertinent to this conversation was the suggestion that the REST Web-APIs should be co-developed in a private GitHub repo with pull-requests as the way of progressing the design and implementation. This would wholly replace the meetings, weekly conf-calls, word docs, email chains, diverging attachments, etc. I will claim this is a technology compatibility kit (TCK) utilization but make the case for that claim gradually in this article.

The GitHub repo (the TCK) would be private to both parties and contain a reference REST implementation. That could (say) be in Ruby’s Sinatra tech with related tests that would exercise those endpoints in (say) Ruby’s RSpec or Cucumber. The reference implementation would be minimal. For example - no database at all, just structured but hard-coded “Fred & Wilma Flintstone” style data. Or whatever that would pass as minimal and exhibit several known behaviors for given scenarios.

Either side could propose changes to the Web-API services in code. They could do so as long as they also made changes to the tests that would pass against the same implementation changes. That proposal would be in GitHub’s “pull request” (PR) mechanism. The consumption of the PR into master would mean the other side was happy with it and was ready to go on their side with agreed immediate deployment of the (say) QA stack. Debate and refining of the precise nature of the code in the PR would happen in the GitHub code review tool. So would outright rejection, if desired by the other party. Of course, phone calls would still happen, but the system of record would be the tools inside the private GitHub repo.

As it happens, both the airline and the vendor were using Java so this TCK could have used a Java reference implementation and Java tests that would have been closer to their actual production intentions. In the end, though, there’s some elegance to choosing something economic like Sinatra and RSpec for the TCK, as this piece itself is not going to go live. The advanced feature is that the vendor could take the tests from the TCK and run them against the REAL services implementations they were working on. Easier said than done, but certainly possible. And the airline could have taken the reference implementation of the web services and confirmed that their being-developed UI could run against that. Again easier said than done, but still possible. Both of those confirming steps would happen as part of the proposal/acceptance cycle for pull requests on the TCK itself. They are implicitly done from the point of view of the other side. What I mean by that is that test-results are not copied back into the pull-request or shared any other way, but are acknowledged as done. At least, according to the rules of developing this way. One would presume that visits to the other side’s development office could occasionally confirm that “we” had seen “their” expanded tests actually running.

So a reference implementation and corresponding tests (in a repo) is one thing, but the gold standard would be a formal service virtualization technology used in TCK manner. There are more than 20 choices for technologies for that. Wiremock would be attractive for two Java teams. Mountebank by former colleague Brandon Byers is very compelling, but the Servirtium thing that I have been working on is the one I was thinking of. Specifically, because it’s scenarios were in relatively plain markdown and external to the 3GL in question. Markdown being many times better than JSON or YAML for encoding request/reply if you’re going to discuss them in a PR towards a yes or no decision.

While Servirtium is primarily a record and playback tool (like Ruby’s VCR), it is entirely possible that the markdown conversations themselves can be the basis for changed service definitions. For example seat_is_no_longer_available_indicated_in_attempted_progression_to_payment.md could be cloned into seat_is_no_longer_available_indicated_in_attempted_progression_to_see_rental_car_choices.md for discussion ahead of implementation. Of course, cloned along with the corresponding test. The markdown format noting the interactions of the test scenario is relatively easy to read. And as such, they are relatively easy to clone for “proposed change” purposes and discussions. For more situations that just a client and supplier chasing release dates for a co-developed piece of software.

My wish would be that API makers ship a range of Servirtium markdown scenarios only. Which of 20 viable 3GL choices the consuming team uses to write their tests with that playback that scenario is their business. Also, how they configure their build automation to confirm those previously recorded Servirtium conversations are still representative of the “real” APIs is also their business, but the vendor should pledge to keep those scenarios accurate over time. Hopefully in a public Git repo (perhaps with a no-reverse engineering license).

Servirtium is being developed in multiple languages concurrently. At the time of writing, we have Java, Kotlin and, .NET versions ready to use. The Ruby, Python, and JavaScript versions are part complete. See servirtium.dev for more info, or github.com/servirtium/README if you’re on top of what it is and want to join in with making an implementation (Rust, C/C++, D, Zig, Erlang/Elixir, Julia, R, Smalltalk, etc).

Lastly a confession: this wasn’t an airline and their supplier, but I’m under NDA to the real client so I changed their “vertical” to airline.