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.

11.1 What makes an API user-friendly and interoperable?

11.1.1 Having a clear purpose that meets focused needs

11.1.2 Enabling discovery and navigation

11.1.3 How to create user-friendly, interoperable APIs

11.2 Creating one or multiple APIs

11.2.1 When to discuss API granularity

11.2.2 Identifying independent sets of operations

11.2.3 Keeping in mind that sub-APIs can be related

11.3 Clarifying the API’s purpose with its name

11.3.1 When to choose an API name

11.3.2 Choosing an API name

11.3.3 Adding the API name to the API base path

11.4 Enabling interoperable API browsing with HTTP and hypermedia APIs

11.4.1 Listing a resource’s operations with the OPTIONS HTTP method

11.4.2 Providing pagination, formats, and resources links with the Link header

11.4.3 Using hypermedia formats for relations and actions

11.4.4 Using content negotiation to select hypermedia or plain JSON format

11.4.5 Ensuring that subject matter data is always available

11.4.6 Considering browsing capabilities

Summary

Exercises