Big organizations are slow to change, especially when it comes to technology. After all, the stakes are high, and the complexity of existing systems is even higher. There comes a time when you can’t put off embracing new technology any longer. That time has come for many. Now, software engineers around the world are working out how to redesign their legacy applications with a RESTful API-first approach.

Chris Busse, the Chief Technical Officer at platform consulting firm Terazo (formerly known as APIvista), shared his philosophy on API-first redesigns at our 2018 Nordic APIs Platform Summit in Stockholm, Sweden. Today, we share those thoughts with you!

APIs for Lemonade Stands

Chris begins his explanation of API-first redesign strategy with a fun, but productive exercise which he employs at workshops. We’ll pass on being too creative and call his exercise APIs for Lemonade Stands.

Continuous deployment might be tricky if you’re delivering software on a cassette.

In 1979, Apple launched Lemonade Stand, a text-based computer game for the Apple II. The game operates in turns and — being a kids’ educational game — couldn’t be simpler. At the start of each turn (representing a new day), the player gets to make three decisions: how many cups of lemonade to make, how many advertisement signs to put up, and how much to sell the lemonade for.

Based on those variables and a weather forecast for the day, the player would sell a certain number of cups of lemonade at their chosen price. After deducting the day’s advertising spend from the lemonade revenue, the game presents a profit or loss for the day and tallies that into their asset column.

At his workshops, Chris introduces participants to the game and then encourages them to play a total of ten rounds in groups on an online emulator. This, Chris says, is what it’s like to use a legacy application. The question is, how does it really work?

What are the rules? What’s the business logic? All we have when playing Lemonade Stand are the instructions presented to us before launching the game. This is akin to working with a legacy app. In some cases, we might be lucky enough to have access to a legacy application’s source code — if there’s someone who can understand it!

Two-Step Redesign

Do we have enough information to redesign this legacy app, API-first? Chris would now ask his audience.

Chris Busse examines API design fundamentals by breaking down the logic of 1979’s Lemonade Stand game.

He proposes a two-step redesign to the workshop participants. In the first step, we concern ourselves with the resources themselves, and in the second step, we’ll worry about payloads, requests, and responses. So, what would the first step look like for Lemonade Stand?

After five minutes, Chris collects the responses. After some discussion, he takes the opportunity to introduce the OpenAPI specification, where he organizes the lemonade stand API across the objects he saw in the game: lemonade (with its quantity), and advertisement signs (with their quantity).

Then they move the second stage of the redesign, at the field-level. After another five minutes of deliberation, they suggest adding POST methods so users can post how many lemonades to make and how many signs to put up in each turn. This “kind of resonates” with the audience…

User-First Approach

Are we sure we’re on the right track? Chris asks.

He goes on to explain that, while playing the game, the true user experience is really represented by progression through the turns. Resources like lemonade and signs, on the other hand, are more of a field-level representation within those turns.

Naturally, some agree, and some disagree, but most acknowledge that you could view it either way. Most importantly, having played the game, participants experience the user journey first-hand. Knowing what the customer has to go through builds empathy, says Chris.

To wrap up the Lemonade Stand example, Chris asks, “How many people had construction crews shut down your street?” While this is a rare scenario, it does pop up in the game at times and demonstrates the importance of the edge cases we as developers tend to push aside.

It’s only natural that we do so, too. Middleware developers are often handed requirements for their solutions and aren’t given the opportunity to sit with users and understand how what they’re building will ultimately impact them.

Chris takes this opportunity to explain that building with a database-first approach, instead of a UX-first approach, is probably what leads to a lot of the criticism about REST. Systems tend to lend themselves better to REST architecture if resources represent something meaningful to the final implementation.

Abstractions

With legacy applications, there’s always the question of abstractions. If you implement a three-tier API layer architecture, you might be able to hold onto your existing applications and build layers of abstractions — from systems, APIs to process APIs to experience APIs — to ensure the end APIs match the user’s needs.

This can be a useful technique, Chris admits. By doing so, you create resource representations that make sense for REST. However, they’re not always needed.

It’s also worth asking: Are you just refinancing your technical debt? For some, abstractions are simply delaying the inevitable — and it’s better to get it out of the way sooner than later — but for others, that buys a valuable five years.

Final Thoughts

API-first redesigns are about empathizing with the end-user and designing accordingly. Chris suggests middleware developers get out of the building and get a chance to sit with those whom their work will ultimately affect, whether it’s consumers, call center reps, or assembly line workers. If you’re in charge of things, make sure developers get that opportunity, especially if you’re redesigning existing processes.

As a related tip, Chris suggests you bring more diversity into development and product teams. Just by bringing in more points of view and diverse backgrounds, he believes you can help cultivate a culture of understanding and empathy.