Walking Through API Design as a PM: Consumers, Resources, Contracts and Versioning

In a product manager interview you are asked how you would design an API. Walk through the approach you would take and the main decisions you would make along the way, explaining why. You may illustrate with an example API of your choosing. ```hint Start from the caller Before naming any endpoints, picture the developer who will integrate with this API and the handful of tasks they need to complete. ``` ### Clarifying Questions - Who will call it: outside developers on a public API, a few partners, or our own internal services? The answer changes the stability promises, authentication and documentation required. - Should I focus on the product manager's part of the work (use cases, developer experience, launch) or also cover the technical choices the engineers would make? - Is there a specific product or use case in mind, or should I choose an example? - Do existing platform conventions or a style guide already dictate the interface style? ### What a Strong Answer Covers - Identifying the API's consumers and their top use cases before designing endpoints, and defining what success means for those developers. - Modeling resources and operations, and choosing an interface style (resource-oriented HTTP, RPC, a query language, event callbacks) with reasons. - Contract details: naming, request and response shapes, error format, pagination, safe retries without duplicate effects, authentication and rate limits. - Evolution: versioning, backward compatibility and deprecation. - Developer experience and launch: documentation, SDKs, a test environment, and adoption metrics. ### Follow-up Questions - A partner's request timed out, they retried, and two orders were created. What in the API design prevents that? - Thousands of integrations depend on a field you need to rename. How do you roll the change out? - Which metrics would tell you the API is succeeding with developers?