We recently surveyed Stoplight customers who are also using API gateways and spoke at length with a few of them about the tools and processes they employ in their API programs. Stoplight users are working in many different market verticals, on teams of widely varying sizes, and in companies at every stage of maturity. Still, we were struck by some constant themes in what technical leaders value, no matter the company or product – tools need to be purpose-built, low friction, usable by both technical and non-technical stakeholders, and reliable over time.

As for why these principles are so widely shared, we think it boils down to something pretty simple: good developer experience is the result of good API product design, and that requires tools that support your efforts. When you combine effective tools, design-first principles, and a product mindset, you get a smoother and more efficient developer and user experience.

Build adaptable APIs with universal design principles.

If you’ve never heard of the Curb-Cut Effect, you’ve almost certainly been its beneficiary. When wheelchair ramps were first mandated at bus stops and crosswalks, all sorts of other people benefitted – parents pushing strollers, delivery drivers wheeling hand trucks, and folks on the way to the airport with luggage in tow. It’s become shorthand for how improvements made for one group of people can often have benefits for society as a whole.

Is there a curb cut for APIs? What changes could you make to your API programs that might make them more accessible? Could you reap some unintended benefits that way? No surprise that we think it’s possible – and that design-first APIs are the way to get there.

One of the most widespread approaches to accessibility is Universal Design. It’s a set of principles for products and communications aimed at designs that are accessible and usable by the greatest number of people in the widest possible range of situations. The full scope of UD is more than we have time for here, and some of the principles aren’t very relevant to software development. But here’s food for thought: the goal of UD — to build products and programs that are usable and flexible enough to meet the needs of diverse users — is definitely applicable to API product teams.

You can’t predict exactly who will be using your APIs or how they’ll employ them, or even who will be building them. UD principles can help you create an API program that will have endurance, flexibility, and appeal. Ask yourself these questions about your APIs:

1. Equitable Use: Are we providing entry points to our APIs that welcome all potential users? Where can we remove barriers?
2. Flexibility in Use: Do we support multiple paths to success for our API consumers? Or are we prescribing a single approach where it’s not required?
3. Simple and Intuitive Use: Is it easy for users to understand what our APIs do? Is it easy to find the tool you need? Do we make installation and authorization processes clear?
4. Perceptible Information: Does our documentation use plain language with clear examples of functionality and navigable resources? What assumptions are we making about what our users already know?
5. Tolerance for Error: What happens to users who don’t follow our preferred path? Are we providing useful error messages within applications? Do we have documentation to support troubleshooting?
6. Low (Physical) Effort: Do we offer easy ways to explore, test functionality, and build trial integrations? Is the auth process quick and predictable? Where are users’ pain points? Are we creating an unnecessary cognitive load anywhere in our user flow?
7. Size and Space for Approach and Use: Are our API resources usable with screen readers? Are they visually organized in a way that’s manageable for low-vision users?

In our conversations about API gateways, we realized that Stoplight customers are addressing many of these concerns with these tools.

Choose tools that help diverse companies solve common problems.

It’s not just API users and use cases that have varied, evolving needs – API companies themselves are an increasingly diverse group. Two Stoplight customers we spoke to recently show what we mean.

APIs deliver reliable, innovative GIS data for public safety.

The founders of GeoComm were among the first to apply modern GIS (Geographic Information Systems) data to emergency response services, beginning in 1995. Since then, they’ve continued to innovate to bring more and better location data to public safety agencies, including making extensive use of APIs.

GeoComm is a highly specialized company, working with mission-critical data in the highest stakes situations. Keeping their energy focused on their core competencies is essential. Serving public sector agencies, they try to keep costs low and operations lean, while still maintaining the highest quality product. They’ve been happy with the quality of open-source tools, like the API gateway they use for their Kubernetes-based applications and Stoplight Elements, where they host their API documentation. These tools let them manage costs and put their energy where it really matters, so they can deliver better public safety tools.

APIs Help Companies in transitioning to Mobility Solutions Provider

Bridgestone is a leading tire manufacturer and has been in business since 1931. The Bridgestone Group has approximately 130 manufacturing plants and R&D facilities with premium tire, solutions, diversified products, and exploratory businesses in more than 150 countries and regions.

Bridgestone’s Solutions business is focused on amplifying value to the customer when using Bridgestone tires. With more and more vehicles becoming connected with the help of IoT and ICT-related technologies, data is generated about the vehicle and its components to help in managing and reducing downtime. Tires are also becoming increasingly connected as part of this trend, with data being collected about tire-related performance. Bridgestone’s ambition is to be the best at extracting actionable insights using a combination of their leading expertise in tire design and development, extended servicing footprint, and digital platforms/applications.

As a Mobility Solutions Provider, they’re using the power of APIs to integrate with various Partner Systems. To that end, APIs are front and center in their business strategy, which necessitated a complete revamp of the entire end-to-end API program. Part of this broad initiative led them to adopt a shift left Design approach to have a more customer-centric approach towards API development involving internal and external stakeholders early on in the Design process. Some benefits from this approach are increased development speed, reduced cost due to API rework, and co-value creation

We spoke with Ajay Joseph, Cloud Operations and Developer Experience Lead, about their API programs and how they’re expanding access to their data assets and driving innovation with partner integrations. Joseph sees Bridgestone increasing API adoption in the future, as it plays a vital role in their overall business and technical strategy. When choosing tools to support their API programs, Joseph prioritizes ease of use, quick onboarding, improving the productivity of collaborative work, and enforcing cohesive and consistent standards as part of overall Governance.

Their choice of an API gateway was straightforward – they chose a native solution from their cloud provider because it was the most intuitive and consistent, and made it easy to streamline processes across teams.

Those principles also steered Bridgestone’s API teams towards Stoplight. They needed a tool that would allow their Product Owners to be directly involved in the API design process without requiring too much technical knowledge. Stoplight onboarding has been very quick for both technical and non-technical stakeholders, and they’ve found the collaboration features intuitive for people who are already comfortable with Microsoft 365. The built-in Style Guides allow their API designers to follow consistent standards based on Global best practices. When tools serve these goals well, it frees up API teams to focus on the business value of their work, ultimately helping Bridgestone meet its goal of being a sustainable solutions company.

Open the right doors and provide a good map.

Why does Stoplight form such a powerful combination with an API Gateway? Think back to those principles of Universal Design — together; these tools help API teams address each of those elements:

1. A gateway helps reduce technical barriers to API access, and Stoplight helps ensure your documentation is up-to-date and readily accessible, improving equitable use.
2. Gateways and collaborative design tools help a variety of stakeholders engage with your API products through a single predictable interface, supporting flexible use.
3. API tools explicitly designed to simplify complex systems and increase consistency will allow users to move between functions and products intuitively.
4. Gateways and Stoplight tools are meant to make your APIs more human-friendly and place a premium on putting critical information where it is needed most — and, generally speaking, they’ll be continually improving accessibility so that you can make information perceptible to all of your API users.
5. While building systems with tolerance for error is important, using an API Gateway is a great way to establish a clear preferred path for users and reduce the potential for error in the first place. Stoplight design tools can help you lay out your pathways effectively, and great documentation helps users navigate when they’re uncertain about how to proceed.
6. As the two examples above show, choosing the right tools helps reduce the cognitive load and eliminate stressors for your API teams – once they’re in place, your API tools should be a low effort so you can focus on creating value with your APIs.
7. This one is a bit of a stretch, but even small improvements in visual organization, whether through your gateway, your docs, or an API catalog, can lead to gains in productivity by giving users the space to see the different pieces of your API program clearly.

We suggest thinking about your API tools, in particular your design tools, gateway, and documentation solution, in terms of establishing a smooth path for your API stakeholders. UX designers use the concept of a “preferred pathway” to talk about how potential users move through a website or application. When users follow the preferred path, they experience less frustration and gain a better understanding of how the product functions and what possibilities it offers.

The same rings true for developer experience! You don’t know exactly what developers will do with your APIs, but you know there are better and worse ways to get started on the path of discovery. Sending developers down the right path is a matter of opening the right doors and providing a good map – which Stoplight is ready to help you do!