11 Designing user-friendly, interoperable APIs
This chapter covers
- Creating one or multiple APIs
- Naming APIs
- Enabling interoperable API browsing
We are not easing developers’ work if an application must use different APIs but their search operations have completely different designs or similar resources have different IDs in different APIs. But before that, developers must find the right APIs and understand their capabilities and how to use them to meet their needs. But suppose an organization’s information system is divided into two dozen blocks, each exposing an API just named “API” comprising hundreds of operations. Anyone (human or AI), including those who have created them, will have difficulty finding the right APIs and operations they need.
Ensuring the design of globally user-friendly, interoperable APIs is essential, as we’ve covered in previous chapters. But we must see an API as a whole and understand how to facilitate its discovery, understanding, and usage. This chapter examines what makes an API globally user-friendly and interoperable. We then explain how to choose between one or multiple APIs and how to select API names to help developers find and understand our APIs. Finally, we discuss enhancing API interoperability and enabling runtime discovery by adding browsing capabilities and creating a hypermedia API.