The Role of An API Designer

APIs are everywhere, and enterprises want in on the action. Senior executives at various medium-to-large companies have been sold on the value that great APIs can bring — both for internal and external uses — and have started setting up Enterprise API Programs to support these efforts. But despite the best intentions and true commitment that got these programs funded and started, many obstacles remain to instilling an API-first culture that supports a great developer experience.

One approach to prioritizing an API-first culture is the introduction of a new role in enterprises, that of the API Designer. But before we dive into a deeper definition of the API Designer’s role and place in the organization, we should first look at some of the challenges that exist today in enterprises trying to make this transition.

Legacy Infrastructure

In all likelihood (almost by definition), an enterprise’s technical infrastructure is an amalgamation of acquired technology, half-implemented programs and miscellaneous one-off projects done with expediency in mind. Maybe you have some kind of SOA middleware implementation, an Enterprise Service Bus (ESB), a canonical enterprise data model and have structured some large applications around that.

Specific implementations will, of course, vary wildly between organizations. But common characteristics would include a heavier focus on centralized consistency rather than distributed autonomy, developer experience and usability.

Legacy Culture

Beyond just having a legacy infrastructure, unless there’s been 100% turnover of people in your company, there will be a legacy culture of getting things done the “old way”. It’s a rational response when faced with ongoing business concerns that are being met with current technology. Beyond being rational, it’s not actually something that you can (or should desire to) eliminate in one fell swoop. Rather, you can start replacing culture the same way you switch out a system or database by doing the following:

  1. Build new culture on the side, separate from existing one
  2. Run both at the same time, but with the old culture still being the official one
  3. Run both at the same time, but the new culture becomes the standard bearer
  4. Wash, rinse and repeat until you reach a cultural tipping point

It should get easier as you go and as the business executives start to notice some areas moving faster than others. It becomes easier to get buy-in for each incremental project.

Silos of Complexity

A large enterprise is large for many reasons, but one contributing factor is that as the market and business matured, the organization grew in order to cover that complexity and scope. This means that there are groups in the company that work in silos, tackling their small slice of the complexity of the overall organization. Even within those silos complexity exists, down to a seemingly infinite level, like a fractal, stopping only because the organization has no more resources to apply to the problem.

Once again, you can’t change this entirely, but you can actually use it to your advantage. Silos provide natural break points to impact culture and technology choices. As long as you can find a silo that aligns to a business problem, you’ve got a chance!

Understanding and navigating the challenges of an enterprise is just the beginning. Once you’ve done that, you still need to find ways of making your API add business value. In finding ways to do this inside an enterprise, there are two key principles that you can use to figure out what to do next.

APIs Must Reflect the Business Vision

Despite almost everyone in an enterprise thinking they know what the business should be doing, or even thinking they know exactly what the business is about, they probably don’t. Keep in mind, almost everyone in the company is working knee-deep in a silo of complexity. These silos might be focused on things that represent today’s business needs, not tomorrow’s business goals and opportunities.

Do not lose hope. There are people in the business who have a vision of where the business needs to be to succeed, and the key levers that make it run (if you are in a company where this is not the case, leave now!). They are Directors, VPs, and Program Managers. They are the folks who have the ear of the C-Level execs.

The key is to tap into the knowledge of these people, carve out boundaries in the silo that can carry that vision, and figure out how to represent it with a set of great APIs.

Your Customers are Developers

You might understand the business vision and have a good sense of what business value you need to communicate. If you don’t validate your assumptions as you go with your target market, then you’ll end up building the wrong thing. The startup world has figured this out, but it’s easier for them (though still not easy at all) because they are small enough to have a tightly focused loop between the success of their product and the market they are serving.

An API built to reflect the business vision needs to be developed using the same principles. A tightly-focused feedback loop is needed with the people who will be using the API you’re building. This analogy extends to more than just finding a group of developers to test and iterate the API design. You need to find the right developers, ones who are incentivized to care about that business vision you are trying to articulate in the API. If you only test the API with developers who are building a legacy application, they will only be concerned with legacy needs.

How do you package this up and deliver great APIs? The challenges are significant and a new role is needed to help bring focus and clarity to the API space. API Designers can move the needle on Enterprise API Strategy. By structuring a role that is focused on structurally addressing the two principles above in a targeted way and filling it with people who bring API expertise and a deep understanding of Developer Experience to the table, lasting change is possible and value can be created.

The API Designer focuses on the following:

  • Best practices and patterns for modern API design and Developer Experience
  • Understanding the business vision, value for a well-scoped business domain, and translating it to a great API Design
  • Acting like a consumer and tightening the consumer feedback loop by facilitating feedback sessions with target API consumers as part of the API design process
  • Introducing modern API tooling and design practices into the Enterprise
  • Contributing to best-in-class documentation, tutorials, code libraries and sample code
  • Working with API Developers to navigate and overcome the constraints of the legacy architecture

If done right, you will be the standard bearer for APIs in your company. If you’re a believer in the power of APIs like I am, getting this right means you’ll have a significant impact on the business.

DISCLOSURE: The opinions in this blog are the opinions of the authors/interviewees and not necessarily the opinions of Capital One. Unless noted otherwise in this post, Capital One is not affiliated with, nor is it endorsed by, any of the companies mentioned. All trademarks and other intellectual property used or displayed are the ownership of their respective owners. This blog post is © 2016 Capital One.