26 April 2021
With a well-designed API, service providers can stand out from their competitor’s products and be more successful in the market. To design APIs well, the right approach and some adjustments in the company are necessary.
In the previous blog article (APIs for Next Generation Products), we noted that APIs are not just a technical detail in the IT department’s area of responsibility but have become an essential part of a service offered to customers, and as part of the product, they also require professional product management.
For the APIs to be successful, they must be designed and maintained with the right mindset:
Product Managers are in the Lead
APIs must be managed as part of the product. Accordingly, product managers are responsible for determining what the API offers. The basis for these decisions is an analysis of customer needs and the market.
Developers are at the Core of the API Economy
APIs should meet the needs of API users, i.e., the needs of the customer's IT staff, and especially of their developers. One of these essential needs is to be able to deploy APIs quickly and with low implementation costs. So, product managers need to put themselves in the shoes of the IT people when designing the APIs and related tools. This requires awareness of the importance of an easy-to-understand API, professional documentation, good examples, and a sandbox (environment) for testing. The term "developer experience" was coined for a reason.
Developer Experience = Customer Experience
From this perspective, it also makes sense that IT alone is not enough to create good APIs. The same as other IT projects where UX designers are called in for the user interface, technical writers for the manual, etc., similar specialists are needed for APIs.
Testing, Testing, Testing
Whether a good developer experience is achieved and whether the API in the proposed form is suitable for the entire target group cannot be assessed based on the API design alone. Tests are necessary for this. Both internal tests and support for the first API users are possible.
From our experience, addressing APIs outside the IT department and treating them as an essential part of the product is a new topic for many companies. Product managers are suddenly expected to deal with a supposedly technical topic, but the required skills are not yet available. Collaboration and division of labor with the IT department harbors potential for conflict.
New Mindset
In short: This is a new challenge and requires a culture change in the company.
To establish a new mindset for the novel approach to APIs in the company, comprehensive measures should be taken.
- Product managers are selected to be responsible for APIs. The necessary API know-how is built up in the product management team.
- Responsibilities for implementing APIs are defined: What are the responsibilities of the product manager(s), and what are the responsibilities of the IT department? Which specialists (technical writers, API designers, etc.) are usually called in?
- Guidelines and instructions are created to help design APIs that are consistently designed and documented.
- Quality assurance for APIs, particularly for API design, is established. This ensures that an API is thoroughly tested for good comprehensibility, ease of use, and suitability for the target group before publication. Incomprehensible and unfit APIs are not set live accordingly.
- Information events and other communication measures ensure that API awareness is broadened beyond the people directly involved.
- Rapid implementation of an initial API helps to gain experience and accelerates the learning process within the company.
Conclusion
If APIs are not managed systematically, an API jungle with inconsistencies, unnecessary complexity and missing documentation will emerge in no time. This inevitably leads to APIs that are hardly used but expensive to provide and maintain. Thus, one fails with APIs all the way.
The challenges are usually not of a technical nature. The technology is available, and the IT department has mastered it. Instead, the focus is on establishing an API mindset: making APIs a business issue, making organizational adjustments, and establishing good teamwork between business and IT.
With the proposed measures, one should succeed so that APIs become a success factor of the services and the company.
