chapter one

1 What is API design?

 

This chapter covers

  • Web APIs
  • The importance of web API design
  • When to design web APIs
  • Who designs web APIs
  • How to design web APIs

Web application programming interfaces or web APIs are crucial in our connected world. Whether seen as technical software interfaces or products, they are used by organizations of all sizes and types, from startups to large corporations and government entities. They enable data display and collection in internal or public-facing web and mobile applications and enable communication between server applications. Web APIs allow users to share photos on social media, check bank balances, and hail cabs from their phones. For developers, they simplify adding telecom or payment services to applications without the need for specialized expertise.

The design of any web API is crucial, whether 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.

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 designing 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