API Design

Infrastructure decisions about APIs impact everyone who relies on the service.

The essential principle behind designing APIs is users first. Interview prospective users with specific questions about current and future use cases.

APIs support developers. Getting the correct semantics and building something that feels good to use is critical.

Every small decision makes a difference when designing APIs.

Enable teams to review developer experience processes and improve the frontline tools. Make available standard client libraries in many languages and API references. These tools can be auto-generated.

To infuse a culture of API design at many levels of a product or engineering organization. First, very top-level API resources should be easy to understand and map to concepts related to the domain.

APIs need to be composable. They should be additive building blocks. Fit together. The goal is that any platform component will work with every other element whenever there’s an edge.

Provide idempotent functions. Users should be able to rerun processes without worrying about duplicating changes.

Start with a design document that proposes a new API specification. It details any new endpoints API resources events or changes to response parameters or webhook behavior.

Define a cross-functional review team with expertise in platform operations, developer experience, front-end tooling, and security practices.

The group discusses whether these changes are consistent with the design patterns we have across the API. Will the experience feel consistent when using different programming languages?

Conduct user testing to learn how actual users might adopt the new features. What tensions might come up, and then we produce an early version?

Use infrastructure to gate specific users. Provide as much early feedback as possible on what is a real working API that hasn’t been yet shipped to all users.