1 What is API design?

Think about your past experiences with web APIs. Have you struggled with cryptic or inconsistent naming and typing, poor data organization, or missing data or operations? Spent hours debugging a failed call that returned a vague "Bad Request"? Have you dealt with crashes due to data being removed in API responses? Maybe end-users complained about slow performance, only for you to find an API call returning an entire database table. Or worse, have you discovered an API exposed sensitive data inappropriately? The root cause is often the same: poor API design.

The design of any web API is crucial, whether it is used by thousands of third parties or a few internal developers. Poorly designed APIs can negatively impact developers' productivity, an IT system’s performance and integrity, end users' experience, and an organization’s revenue. Well-designed APIs give developers and IT systems superpowers and make end users happy, helping individuals, teams, departments, or organizations achieve their IT-system-dependent goals faster and more efficiently. In this book, we’ll introduce you to techniques and tools that will help you design web APIs that developers will love to use.

1.1 What is a web API?

1.1.1 A web API is a remote interface for applications

1.1.2 A web API leverages the HTTP protocol

1.1.3 A web API is an interface to an implementation

1.1.4 A web API is an interface for others

1.2 Why does the design of any API matter?

1.2.1 What if a terrible API was a kitchen appliance?

1.2.2 Poor web API design impacts developers and architecture

1.2.3 Poor web API design puts security and infrastructure at risk

1.2.4 Poor web API design impacts end user and third-party experiences

1.2.5 Taking care of design unleashes the power of APIs

1.3 When to design web APIs?

1.3.1 Any new API must be designed

1.3.2 Any modification of any existing API must be designed

1.3.3 Design happens between choosing to create an API and coding it

1.4 Who designs web APIs?

1.4.1 The three profiles needed to design an API

1.4.2 The stakeholders influencing API design