11 Designing an API in context

In the previous chapter, we started to discover that the APIs we were designing were created ignoring most of the context in which they exist. We explored the network context and how it can impact the design of APIs. But there are other contextual elements to consider in order to design APIs that will actually fulfill all your consumers' needs and also be implementable. As we’ve seen, designing APIs requires us to focus on the consumers first, but it also requires us to keep an eye on the provider’s side.

Do you know how the QWERTY keyboard layout was invented at the end of the 19th century? The most common story is that it was created to solve a mechanical problem. On a typewriter, letters are mounted on metal arms that can clash and jam if two neighboring keys are pressed at the same time or in rapid succession. To avoid this mechanical problem and allow users to type faster, commonly used letter pairs were placed far away from each other. This story, if true, means that the QWERTY design was influenced by internal concerns. But according to Koichi Yasuoka and Motoko Yasuoka from Kyoto University¹ 

11.1 Adapting communication to the goals and nature of the data

11.1.1 Managing long processes

11.1.2 Notifying consumers of events

11.1.3 Streaming event flows

11.1.4 Processing multiple elements

11.2 Observing the full context

11.2.1 Being aware of consumers' existing practices and limitations

11.2.2 Carefully considering the provider’s limitations

11.3 Choosing an API style according to the context

11.3.1 Contrasting resource-, data-, and function-based APIs

11.3.2 Thinking beyond request/response- and HTTP-based APIs

Summary