Choosing Between Good and Bad APIs

Prabath Ariyarathna

There is a common myth that good APIs are hard, but bad APIs are easy. But is that true? Let’s see how true this is. In this article, we will only focus on whether an API is good or bad based on its design. There could also be other reasons in other parts of the API lifecycle.

What are good APIs?

A good API is characterized by a clear and concise design, featuring an intuitive structure with consistent naming conventions. Emphasizing ease of use, it provides comprehensive, up-to-date documentation, minimizing the learning curve for consumers.

Consistency is maintained in response formats, error handling, and behavior across functionalities. Flexibility allows adaptation to various use cases and environments, while reliability is demonstrated through stable performance, minimal downtime, and effective error handling. Security measures, such as proper authentication and authorization, protect against vulnerabilities. The API is scalable to handle increased load and growing user bases, and versioning supports backward compatibility and consumer choice. Regular updates, responsiveness to consumer feedback, and optimization for speed and performance contribute to a well-rounded and exemplary API.

Why API design first is important for good APIs?

In our development process, we adhere to an API design-first approach, ensuring that APIs are crafted with careful consideration of both business and technical requirements. Rather than solely focusing on meeting current needs, this approach prioritizes a comprehensive design that anticipates future demands. Properly designed and documented APIs play a crucial role in facilitating effective execution across all stages of development. It is worth noting that APIs designed with a “design-first” mindset tend to be more robust and versatile, ultimately contributing to the overall quality of the APIs developed using this methodology.

Why do people think good APIs are hard?

The API lifecycle involves various stages, and efforts differ at each stage. The main three stages of the lifecycle are design, build, test, and release.

To ensure the quality of APIs, stakeholders at various stages must put in extra effort. This article specifically focuses on the added effort needed during the design stage. Different organizations operate at distinct API maturity levels, each with its own requirements and thought processes. Nevertheless, effective API design is essential for any organization. Crucially, APIs should align with business requirements. If APIs are treated as products, they must also align with the overall portfolio vision. Conforming to proper standards defined by the protocol and thorough documentation is a must. While these are primary considerations, there may be more to explore.

Establishing a proper governance process with the necessary standards is crucial for an organization to achieve the desired qualities of APIs, and this requires additional efforts. Many organizations that neglect API quality often find these processes challenging to implement and time-consuming.

Are bad APIs easier to create?

Organizations often choose an easier path for creating APIs due to various reasons, such as:

1. Prioritizing speedy product development over meticulous planning and adherence to standards.
2. Holding the belief that internal APIs don’t require strict adherence to standards and documentation.
3. Insufficient education on APIs.
4. Treating APIs merely as tools for integration.
5. Limited awareness of the long-term benefits of standardized processes.
6. Resistance to change or reluctance to adopt new industry best practices.
7. Lack of a dedicated API governance framework within the organization.
8. Insufficient allocation of resources for proper API design and documentation.
9. High turnover rates lead to knowledge gaps in API best practices.
10. Lack of awareness about potential security risks associated with poorly designed APIs.

There are several other reasons as well.

Most of the time, organizations simply follow a code-first approach to reduce design time and effort. Considering it from their perspective, bad APIs are easier to compare with good APIs if we only evaluate them superficially without delving deep into the underlying issues.

Can that be truly effective?

As per the National Institute of Standards and Technology (NIST), the cost of identifying and correcting defects in software grows significantly as time progresses in the software development process. Fixing bugs that are discovered after the software has been released can be extremely expensive and risky, generally costing significantly more than fixing them at earlier stages.

Starting with good API design early on helps catch potential issues ahead of time. While it may take a bit more effort compared to rushing through a design, the benefits pay off. Well-designed APIs are easier to read, reduce support hassles, make customers happier, and also offer added perks like better security, scalability, and adaptability for future changes. It’s like an upfront investment that makes everything smoother in the long run.

Based on my experience, introducing proper standards and practices within an organization can be challenging during the initial stages of adaptation. However, as the team gains experience, these practices seamlessly become a part of their day-to-day activities, requiring no additional effort to execute. Eventually, the development of good APIs becomes ingrained in the organization’s DNA.

Summary

Creating bad APIs is easier when we only consider the effort needed during the design phase. Initially, it might seem quicker and cost-effective. However, when evaluating the overall process and the benefits, well-designed APIs offer significantly more advantages to the organization. It’s akin to constructing a house without a proper design — initially, it might seem quicker and cost-effective, but later on, challenges arise due to the lack of proper planning. Fixing these challenges demands more effort and money than investing in a well-thought-out design from the start.

Prabath Ariyarathna

Co-founder and Chief Product Officer at X-venture