- gustavo's personal blog

The Design of Web APIs

My notes on the book The Design of Web APIs. I highly recommend it as a great resource on designing high quality RESTful web APIs.

Fundamentals of API design

What is API design?

Why API design matters

The elements of API design

Designing an API for its users

The right perspective for designing everyday user interfaces

2.3 Identifying an API’s goals

Identifying the whats and the hows

Identifying inputs and outputs

Identifying missing goals

Identifying all users

Using the API goals canvas

API Goals Canvas

Avoiding the provider’s perspective when designing APIs

“Any organization that designs a system (defined broadly) will produce a design whose structure is a copy of the organization’s communication structure.”

Designing a programming interface

Designing the API’s data

Striking a balance when facing design challenges

Understanding why REST matters for

Describing an API with an API description format

Designing a straightforward API

Designing a predictable API

Designing a concise and well-organized API

Designing a secure API

An overview of API security

Partitioning an API to facilitate access control

“Every feature that is added to an application adds a certain amount of risk to the overall application. The aim for secure development is to reduce the overall risk by reducing the attack surface area.” OWASP

Designing with access control in mind

Handling sensitive material

Evolving an API design

Designing API evolutions

Versioning an API

Designing APIs with extensibility in mind

Designing a network-efficient API

Overview of network communication concerns

Ensuring network communication efficiency at the protocol level

Ensuring network communication efficiency at the design level

Designing an API in context

Adapting communication to the goals and nature of the data

Observing the full context

Choosing an API style according to the context

Documenting an API

Creating reference documentation

Creating a user guide

Providing adequate information to implementers

Documenting evolutions and retirement

Growing APIs

The API lifecycle

Building API design guidelines

Reviewing APIs What could go possibly wrong

Challenging and analyzing API needs

Communicating and sharing