User-focused API Development

By CIOReview | Wednesday, May 31, 2017

As componentization becomes the new mantra for software development, the importance of application program interfaces (APIs)—used to link different components within and outside the software, increases. This has resulted in companies prioritizing API development to guarantee a seamless functional integration of components, as well as serve the intended users. Therefore, developing an efficient API requires a thorough understanding of the application architecture proposed to be integrated. Further, as the final product is exposed to the users, the design process of an API must essentially factor their convenience.

Role of Users in Ensuring API Quality

Usability plays a key role in deciding an API’s quality as the machine/system interface is used by people. Therefore, a good API is not merely about well structured software, but also about catering to human factors. Some of the ways in which the human factors can impact API quality are as follows:

• Internal or External Users: Typically, when organizations develop APIs for their internal use, the systems and the data are usually linked in some way, which leads to the adoption of “shortcuts”; the abstraction process during design and development phases is largely simplified, which leads to the system components being tightly coupled — where one component would not function without the other. This caters only to a specific use-case. Therefore, it is vital to target all API projects at external users, for catering to a greater number of use-cases as opposed to a few.

• Documentation: The presence of adequate supporting documentation enhances API usability. In the case of APIs developed for internal users, the absence of documentation could be substituted by conversations with experienced personnel. This however, is not the case with external users. Therefore, a well designed API (which is developed as one targeting external users), is always well documented and its content, easily understood.

• Attributes: In cases like the APIs for SMS gateways or others, people working on the user interface are required to specify the value of each attribute for the API to carry out the functions. This needs to be taken into account as it impacts the user experience. A well-designed API has a minimum number of attributes to perform all the desired functions.  

Business Model: When a company developing APIs, enters into a partnership with another for product integration through APIs, the exact business model needs to be considered. For example, if the customer opts for a ‘pay-per-use’ model and crosses a certain threshold, then he could be entitled to other benefits, which the API could provide. Further, the required levels of customization for each client needs to be taken into account, as benefits could scale with payments.

User Research for API Design

Having examined some of the factors that could potentially impact the API quality, it is now prudent to look at how developers actually go about researching the ways to provide maximum benefit to the end-users of APIs.

The user research is essentially a three-step process, with the first being used for designing the best-in-class experience for the users, to enhance their perception of the application. The second process is ideation, where use-cases are sketched by developers to ensure that the proposed API caters to as many as possible. This tests the creativity of developers and therefore, the more comprehensive the ideation phase, better the outcome. Adequate care is taken to ensure that the API is easy to read and work with, but hard to misuse. The third and final step comprises of testing and validating the entire process of development, which can be accomplished either through manual or automation modes.


API development is a crucial part of both development and usage of software today. Although the APIs are meant to integrate different components within a system, adequate care needs to be taken to ensure that user experience for the final product, without compromising quality. Further, the design phase must involve a thorough research to decide the number of user-cases that the proposed API needs to cater to. Adopting the same approach for developing APIs for both internal and external users, is always beneficial, for it can avoid the pitfalls of shortcuts resulting from improper abstraction, and serve a greater number of use-cases. All APIs must be well documented to simplify their usability.