Five Things That Should be in Your Developer Toolbox

Episode Summary: Michael Hibay, CTO of Vesti and previously senior engineering manager at Capital One, shares with the API Intersection crew the importance of design affordance, customer understanding, and how to get the right people in the room to have those conversations.

You can create the highest quality API, but if you don’t have the correct language, capability understanding, or naming conventions to talk about your API…it won’t matter. I sat down with Vesti CTO Michael Hibay to discuss how developers can create a consistent language and shared understanding across their teams.

In our recent podcast, we talked with Michael about how to equip your developers with the right tools to successfully create quality APIs. Let’s dive into what you should include in your developer toolbox.

1. Design For Your End-Users from the Outside-In

“I’d say there are two truths that are true regardless of scale. One, you need to design from the outside-in for your consumer. Two, you need to respect the laws of physics and design appropriately to be able to handle the complexity that comes when you inevitably run into it.” – Michael Hibay.

In our conversation, Michael focused on the importance of organizational structure when it comes to scaling. Looking at your APIs as products is key for designing from an outside-in perspective.

“Outside-in” describes the concept of aiming to deliver a product that customers want and value rather than focusing on developing products to sell.

With an outside-in approach, developers can better understand the end result of their APIs, whether that’s going from a smaller organization to a larger one or vice versa. Regardless of your approach to API design, the end user’s experience should be at the forefront of your design thinking.

To see how some of this shows up in one’s own organization, Michael explained that APIs are really an abstraction layer, the digital representation of one’s business. Suppose your team starts noticing issues such as leaking out implementation details or showing off organization structure. In that case, that’s a pretty standard error that results from groups not operating from an outside-in model.

2. Remember the Catalog of APIs is Not as Relevant as the Affordances (Language)

“I’m exploring this notion myself. One of the things that’s really common when you get to a Capital One or Vanguard scale is that you run into many different capabilities in your system. Depending on the organization’s maturity of different groups, you may have services and APIs that are coming together and are synonymous. And that’s where the API catalog and service catalog start to blur,” – Michael Hibay.

As your API program grows and your overall organization expands, developer teams can often run into issues of redundancy, incompatibilities, and more. A lot of these issues can stem from the way that API design is talked about internally, and it’s the semantics that creates the root of the problem. There needs to be consistent meaning and understanding between the APIs and the teams building them, as well as the end-users utilizing them.

Michael notes that as an example, if an end-user is trying to add in a contact, it doesn’t matter to them whether or not it’s a user profile or an organization-level contact; because it possesses the same capability. As the developer, you need to note that when naming or talking about the API to produce clarity and eliminate redundancy.

As for affordances, the definition we decided on in our conversation was that an affordance is a potential capability outside of any particular context. In the contact example, the contact is a reusable affordance amongst a variety of other kinds of use cases or resources.

The bounded context implied underneath that contact creation API example could have a big catalog of contacts that are used in a variety of different contexts. Still, it needs to be built in a way that’s decoupled from everything else to eliminate potential redundancy across other API teams and service catalog offerings.

In layman’s terms, define your capabilities and concepts clearly for your APIs so that work isn’t being done twice.

3. Define Your Messages Early

“Fundamentally, it’s about using Open API documents and those kinds of tooling to get serializations defined semantically to be able to name your messages,” – Michael Hibay.

Naming conventions are essential to your API strategy. We discussed how it’s critical for developers to be able to name their messages to eliminate confusion further down the development and implementation process.

As we found in a recent blog post on API consistency, end users and developers appreciate clarity and consistency in API naming conventions. Once a design choice is made, stick to it.

Utilizing Open API documents to define those messages is a great way to incorporate standardized naming conventions and shared understanding amongst teams.

4. Find the Best Storytellers to Tell That Technical Story

“[When building out the story], I like to gather the people who know their stuff, and I try to keep about a 70/30 ratio of non-technical and technical folks in the room,” – Michael Hibay.

When it comes to the language, naming conventions, and keeping track of the capabilities of your API, it all whittles down to telling that proper story. Developer teams can start the process of identifying the language and naming conventions of their API program by getting every relevant stakeholder in the room, especially the non-technical ones.

Of course, having a customer-centric language is great, but that story of what your APIs intend to be used for has to be told at some point. Getting everyone together with an equal seat at the table is the way to do that. That customer-centric language still needs to be well intertwined in the making of that story and language, but there’s more to it than just that!

Michael emphasizes that if people sense a gathering is a tech conversation, and they’re feeling out of place or unsafe to share their opinions, they will not contribute. So, it’s pivotal to create a space that all backgrounds feel they can weigh in on the matter of how to tell that story and build the foundation of the API language. Everyone needs to be able to understand the potential of APIs and contribute to that story.

5. Take the Theoretical and Make it Practical with the Right Tools

“What’s important are tools like Stoplight Studio or similar, where you can keep yourself out of the weeds of the API. For a developer who’s getting into this world, my advice is to stay out of the details of the code,” – Michael Hibay.

The last piece that is key to a developer’s toolbox is the tangible tool itself to help you take your learnings from theoretical to practical. Michael insists that it needs to be an API design tool that is simple enough to keep your end goal clear while still offering what you need to get the job done.

In the end, Michael shared that the best thing you can do to round out your developer toolkit is to start with defining your concepts and what capabilities you want in your API program. He always starts by answering the following three questions:

• What do you want to answer?
• What are you trying to accomplish?
• And whose responsibility is it to do that?

Start there to define that language and set of capabilities for your API program. It’s remarkable how many problems one can find with three, four, or five different solutions for the same thing. Take a step back and use the right tools to save time and money.It was a pleasure discussing with Michael Hibay on the API Intersection podcast.