In many ways, being a developer is just like any other artisan — when it’s time to use our tools, we need them to just work. You don’t want to spend an hour troubleshooting your hammers and saws and chisels, ruining any momentum you’ve accumulated while losing valuable daylight. In fact, it’s probably even more true for developers since we wear so many hats. Not only do we need to write code, build databases, and coordinate with collaborators, we often have to handle support, marketing, and promotion for the tech we create.

When working with APIs or Software-as-a-Service, developers want them to be as frictionless as possible. They need to function as they’re supposed to without requiring too much maintenance effort. This allows programmers to stay in the flow and focus on remaining productive, building killer products and services, and delivering world-class customer service for their end customers and clients.

In short — if you want developers to use your software, you need to provide an exceptional developer experience (DX). So, how do we craft a developer-friendly platform? Well, to understand a complex subject, sometimes it helps to realize how NOT to do things…

8 Developer Experience Anti-Patterns to Avoid

What does a negative developer experience look like? We recently posed this question on Twitter and LinkedIn. The results were eye-opening, highlighting some common problems that may cause a developer to be wary of the service or abandon it altogether.

All developers stand to benefit by learning from others’ mistakes. And these problems aren’t only relevant to public APIs, either. They could arise within external, partner, or internal facing platforms. So without further ado, here are eight examples of negative developer experiences to watch out for, to help you build the best developer-centric products imaginable.

1. Lack of OpenAPI Specifications

Standardization has been one of the most important aspects in bringing web APIs into the mainstream. Much like the role of standardized parts during the Industrial Revolution, API specifications make communication and collaboration between different applications easy and instantaneous.

That’s one of the main reasons that the OpenAPI Specification is so revolutionary — it creates a uniform format that is easily understood by computers and developers alike. This is why it’s so frustrating when an API just disregards OpenAPI.

On our Twitter thread, developer Jordan Walsh talked about his frustration of having to page through API documentation when simply using the OpenAPI Specification would make this a non-issue.

No openapi specs.. So tired of trawling through pages and pages of information on websites that an openapi spec could easily give me first up.

— Jordan Walsh (@jordwalsh) February 23, 2022

2. Documentation in Non-Standardized Formats

Already, we’re beginning to see a pattern emerging. Developers really want API documentation to be searchable, understandable, and easily integrated into any format they desire. Developer Sidney Maestre expressed his frustration with API documentation being published as a PDF.

Documentation in PDF 📄 format

— Sidney Maestre (@sidneyallen) February 23, 2022

At best, this requires having the documentation open as a separate tab, requiring you to tab back and forth, which is a total momentum killer. At worst, this runs the risk of the file getting lost or duplicated, taking up unnecessary room, and causing clutter on your system.

3. Lack Of Examples

Theo Gough, Chief Architect, Aidence, offered a host of excellent examples of developer frustrations, from lack of meaningful descriptions to formatting restrictions. A number of his complaints had one thing in common, though: a lack of real-world examples of an API in action.

No examples, no howto, yaml only (if only!) No diagrams, no test environment (self service Auth please), no (meaningful) field descriptions, no feedback, no logs, no status page,no cli, no sdk, no documentation

— theo (@theogough) February 23, 2022

Adding even a rudimentary example of how to use an API eliminates so much confusion. It makes things much less abstract and gives users something to model their development after.

4. Manual Integration

One of the main benefits of using APIs is automation. But manually integrating APIs defeats much of their purpose, which is a big reason why standards like OpenAPI are such a big deal. Having to figure out how to configure APIs and make them work together is a major pain and can be a stumbling block toward adopting an API, as noted by Twitter user @StefanTMD.

Having to manually integrate API’s 😮‍💨

— Stefan (@StefanTMD) February 23, 2022

5. Lack Of Consistency

When you’re using an API, you really want to know what you’re going to get — surprises are only fun on birthdays and holidays. Specifically, API developers want to know that the service will work every time in the way they expect.

API strategist Hirok Choudhury talked about this in response to our LinkedIn post. According to Choudhury, poor developer experience often arises when there’s a “lack of predictability, consistency and simplicity while trying to discover and eventually subscribe to an API.” Frequent revisions are another cause for concern for Choudhury, which would also impact an API’s consistency.

For API developers, the message seems clear — it’s a good idea to get your API as stable as possible before making it available to the public. If you do need to make changes, use smart versioning practices that prevent disruptions to your existing users.

6. Questionable Deployment Options

Speaking of versioning, new iterations of an API are supposed to fix problems, not cause new ones. Developer George Jeffcock spoke of his frustration when deployment options introduce more problems than the design and code. “Developers should not also be Operation/Network…bad developers experience,” he adds.

If an API is configured for a particular environment, it should solve problems and make things easier. APIs can be configured for everything from AWS to Oracle to Google Cloud. The rise in content-aware network devices and the proliferation of new architectures like containers and hybrid servers have made deploying APIs more variable, with developers needing to think like network operators. Luckily, new techniques have emerged to deal with these issues, like DevOps and an increase in Integration Platform as a Solution (IPaaS).

If you’re creating deployment options for your APIs, make sure they work in the environment they’re intended for. To do otherwise may result in a bad developer experience.

8. Restricted Access for Documentation

API documentation typically provides a helpful rundown of methods, parameters, and examples of API requests and responses in action. It’s meant to be referenced by active users, but it also provides potential consumers valuable insight into whether the API is right for them or not.

Many of these intricacies are necessary to know before deciding to purchase, which makes asking for permission to access the reference documentation somewhat counter-intuitive for a self-service API, to say the least, as pointed out by Ben Virdee-Chapman on LinkedIn.

Final Thoughts

Many thanks to those who took time from their busy schedules to share their painful developer experiences. By responding to these anti-patterns, API providers have some better insight into how to craft a more streamlined experience.

Remember, APIs are supposed to make our lives easier. If users have to dig through documentation or work excessively hard to integrate an API with their existing stack, they’re likely to look elsewhere.

Developers have little patience for unusable or inefficient API products. To return to our artisan metaphor, faulty APIs are like a hammer with a shaky head — you might grab it by accident before remembering it’s wonky and tossing it back in the toolbox.

But what are some examples of negative developer experiences that you’ve encountered? Leave us a comment and let us know! Let’s all pool our expertise to make the API community flourish and thrive!