5 Developer Tips for Surviving API-First

Know your audience

The first key step in any software project is to find the stakeholders. These are the folks — both business and technical — who will set the game board, make the rules, and let you know if your team is actually winning. Once established, here is a sample of the questions to ask 🕵️:

• What do we feel a successful API-First strategy enables?
• Which of those benefits is most impactful?
• What’s motivating an API-First strategy today?

When business stakeholders answer questions, we do not interject with a correction we believe is more technically correct. Let’s take this up with our developer compatriots when ironing out the details. This keeps us all out of trouble. 🙏

It may be too early to know in the beginning, but a question to plant in everyone’s mind is:

• How do we measure success when moving to an API-First strategy?

Let’s not leave ourselves out of the equation! As members of the development team, our insight is important here, as well.

Speak the language

Sometimes, we just nod and smile when we don’t understand each other. And maybe that’s fine if we’re video chatting during the awkward networking phase of our favorite virtual API conference. When it comes to building software, finding a common vocabulary is a productivity hack.

In Domain-Driven Design, this is known as the Ubiquitous Language. Domain experts know more about how the business functions, and this creates information asymmetry.

According to Eric Evans:

Translation blunts communication and makes knowledge crunching anemic.

When we’re building APIs, we should be mindful of this common language.

• Should the property be called state or status?
• Is it a soft_delete or an eviction?
• Is it a retrospective or a harbinger_of_death?

As we go through this exercise, we will often run into undefined behavior. This is a great opportunity to work together and discover if any shadow processes exist in the business today. Then we can effectively model those workarounds in the API. Beep boop. 🤖

Understand the building blocks

Distributed systems are hard. When we spend time weighing the options, we take a proactive approach to architecture. It takes a lot of practice before we can speed-run our way to victory.

Single Page Apps (SPAs) and APIs are everywhere. They’re the de facto standard for new applications. We could just slap together a quick API to turn SQL query results into a JSON payload. Ship it! 🙈

There are more than a couple of elephants hidden in this labyrinth.

• Which component owns application state?
• What are the trade-offs related to storage, compute, and data transfer?
• What are our API consumer use cases?

SPAs are thick clients in a client-server architecture. A common approach is to let the API act as a thin layer over data storage while moving compute to the Web browser and taking on more costs for for data transfer.

Thinking about our consumer use cases, we can make a decision on which properties and trade-offs make the most sense. Where we give control, we give complexity. If we want to delegate much of the control to the thick client, we can look at a solution like GraphQL. The trade-off is pushing query and mutation decisions to every client application. If we want to centralize that complexity on the server side, we can look at patterns such as materialized views.

Whatever decisions we make, let’s make them deliberately. Documenting these motivations, system capabilities, and trade-offs can give us a cheat code for the next API-First project. And yes, by the time you’re done reading this sentence, the documentation is already out of date. We’re still working on that one.

Plan for next steps

Whew. We did it! Spot bonuses all around! jk jk… No matter how fast or slow we move when building software, one thing is always certain: we got it wrong. Either we missed a requirement or the business needs changed or legislation was introduced or… or… The list is never-ending.

Some of us use humor as a defense mechanism. Here are a few ways we can protect our systems without therapy:

• What are our scalability vectors?
• Where can we find performance opportunities?
• How can our APIs evolve?

HTTP is the most successful protocol of its kind. Let’s steal from it.

Use the network. Communications move through several network layers. We can take advantage of this, often transparently. API Gateways are proxies that apply security, message transformation, custom routing, and more to centralize policy management.

Figure out a caching strategy. This isn’t just part of a terrible whiteboard interview to optimize a search algorithm. HTTP allows caching at the client, the server, and intermediaries. Bust out that Cache-Control header! It’s a quick performance win.

API evolution is a big topic. For now, it’s good to remember that most JSON parsers are forgiving by default. It’s easier to add a field than to remove one. We can take advantage of this. There are also various deprecation signals to evaluate, such as the Sunset header.

Design with intention

There’s always room for exploration and improvement, so let’s do it collaboratively.

API definitions offer a great medium for discussion (not just automation).

Rapid protyping of APIs is only getting better. We can author an OpenAPI definition, generate a mock server, collaborate on design, and start the next iteration all within the same tool.

Success emerges from a combination of many disciplines working together to solve problems and create opportunities. We should make intention explicit. Look to processes like:

• Event storming
• Value-stream mapping
• API Lifecycle Blueprints

The term API-First can have different meanings to different people. Don’t go into the API-First strategy unarmed! To recap:

1. Know your audience.
2. Speak the language.
3. Understand the building blocks.
4. Plan for next steps.
5. Design with intention.

Follow these 5 tips, and you’ll be the next person to take a trip on that CEO’s weird-looking rocket! 🚀✨