Article Summary
Why can APIs and development platforms be challenging—and how can we overcome it in 2025?
– Flexibility creates complexity because powerful APIs and dev platforms are often difficult for users to harness despite their potential.
– Common challenges include a lack of context, limited user guidance, and reliance on small, closed user bases for support.
– Modern solutions feature interactive developer portals, AI-assisted documentation, and guided tutorials to aid exploration.
– The role of documentation is vital as technical documents and structured resources make these platforms both accessible and efficient for developers.
APIs and development platforms are flexible and powerful, but this flexibility often creates complexity for users. In 2025, many of these challenges—such as a lack of context, limited user guidance, and small user bases—can be addressed with modern approaches, including interactive developer portals, AI-assisted documentation, guided tutorials, and multi-format outputs. Proper technical documentation and structured resources make these platforms accessible, usable, and efficient for developers.
In 2012, I collaborated with several customers on a range of projects aimed at making it easier for people to utilise APIs, SDKs, or development platforms.
What all of these have in common is that they’re tools people use to build their own custom applications… and they’re tools which are expensive to support because users require a significant amount of help to use them.
Why is it so difficult to make these products usable?
What do we mean by “API and development platforms”?
Just a quick note before we proceed: in this article, I’m using “API and development platforms” as a shorthand for “APIs, SDKs, and development platforms”. Sometimes I may even say just “API” to mean all of these. Sorry if that causes any confusion. My point is that although they’re pretty different types of things, they do share enough in common for us to discuss them as a group.
What do people working with APIs and development platforms think?
During the projects, I was fortunate enough to speak with around 25 people on the receiving end of these products, as well as the same number of developers who weren’t using the products I was working on, but provided input based on their experience working with other similar products. This gave me a pretty good insight into what’s difficult about using these products … as well as some good ideas about how to do it right.
I talked with these people about:
- How do they go about familiarising themselves with this sort of product
- What they find frustrating
- Type of learning or information resources they found useful
- Specific examples of information they’ve looked up, posted on forums, or contacted support about
- Specific companies or products that do it well or badly
- What makes APIs difficult to use
Want to find out more?
What makes APIs and development platforms difficult to use?
So, what are the difficulties? Here’s a quick overview of the top 10 changes:
1. Flexibility
APIs are, by their nature, flexible: full of potential to become a variety of different implemented solutions. They’re just a set of rules and potential. If people didn’t need this flexibility, they’d buy an off-the-shelf, implemented product. Traditional information and tutorials focus on how to implement a solution; what’s actually needed is additional information that helps users imagine what might be possible.
2. Complexity
Complexity is often an accidental side-effect of flexibility. The more features you add to the tool, the more difficult it becomes for users to identify the features that are relevant to them and determine the best way to implement them.
3. Lack of UI
Exploration is complex. With a GUI or website, people can navigate, click, and explore functionality. Until people are familiar with your API, they don’t know the terminology associated with your functionality, making it difficult to analyse the documentation. They can blindly click on links within the official documentation, but that doesn’t provide much context. To really explore, you need to implement; to implement, you need to know the basics of using the API or platform.
4. Practicalities of delivering supporting information
The type of product or tool often relies on documentation or specifications generated from code; depending on the tools used, this usually restricts what can go in (e.g. graphics and text formatting) and when (i.e. not post-release). This limits your ability to provide information in a usable format.
5. Technical products
APIs are highly technical. They require specialised knowledge to communicate about how to use them, which means expensive people.
Want to find out more?
6. Supporting troubleshooting for a custom-built application – The more flexible a tool is, the more difficult it is to make error-handling relevant and meaningful for an individual implementation.
7. Development processes – Finishing the API reference documentation is often a last thought, meaning it doesn’t get the attention it needs to make sure it is usable, accurate, and complete. Creating additional information beyond the reference documentation doesn’t make it beyond “wish-list” status.
8. Poor requirements management – The API isn’t clearly defined (i.e. in terms of requirements): it’s more usually a by-product of other decisions. No user stories specifically address the use of the API – it simply exposes functionality that already exists for a core GUI product or SDK. It may even include functionality developed for a specific customer or customer demo. Closely related to this is…
9. Poor product management – The API isn’t managed as a product – features are added ad hoc; unused features are rarely removed or deprecated. Information about which features are being used and how is either unknown or not incorporated into decisions about future developments.
10. Small(ish) closed user base – Examples of similar products that provide good usability are often generic development platforms and tools (e.g. JQuery) or even programming languages. These products have a large customer base that is happy to collaborate on forums, blogs, and other public resources. For many of the products I was working with, the user base was smaller and often consisted of individuals working for competitors, so knowledge sharing was not readily available. This meant that users had to rely solely on the official resources provided by the company to learn about the product.
How can we address these challenges in 2025?
In 2025, we have tools and approaches that make most of these challenges much easier to handle. Flexible APIs and development platforms are still complex, but modern solutions help users explore, understand, and implement them effectively:
- Interactive developer portals with live API consoles
- AI-assisted documentation suggestions and search
- Tutorials and guided workflows integrated into the platform
- Multi-format outputs (JSON, XML, GraphQL, gRPC)
- Community-driven examples and shared resources
With these approaches, developers can adopt APIs more quickly, reduce errors, and maximise the platform’s flexibility.
While APIs and development platforms can be challenging, most of these difficulties can be addressed with proper documentation, structured guidance, and modern tools. If you’d like expert advice on creating technical API documentation or enhancing your platform’s developer experience, please don’t hesitate to contact us. You can also explore more of our technical resources, such as How to Make API Documentation & Influence People, or visit our API Documentation Writing Services page.
Frequently asked question about – Overcoming API and Development Platform Complexity
Why does the flexibility of APIs and development platforms often cause complexity for users?
APIs and development platforms are inherently flexible to allow for custom application building. However, this flexibility introduces complexity because without a graphical user interface (GUI), users struggle to explore functionality, learn the necessary terminology, and identify which specific features are relevant to their needs before starting the actual implementation.
What are the primary challenges in making technical APIs easy to use?
The most common obstacles include a lack of initial context, restrictions in traditional code-generated documentation formats, and poor product management where features are added ad hoc. Furthermore, many specialized platforms suffer from having a small, closed user base, forcing developers to rely solely on official company resources rather than public community forums.
How can modern documentation tools resolve these API usability issues?
Modern developer experiences overcome these challenges by implementing interactive developer portals with live API consoles, utilizing AI-assisted documentation suggestions, and providing guided step-by-step tutorials. Delivering content in structured, multi-format outputs (such as JSON, XML, or GraphQL) simplifies exploration and accelerates developer onboarding.
Originally published 30.01.13