API Design Focuses on Developer Empathy
Effective API design for internal tools prioritizes empathy for the developer experience to reduce friction. In an interview on Software Engineering Daily, Airbnb's internal tools lead Priya Shah stated, "most API pain comes from unclear error messages and hidden configuration gotchas." She suggested that internal teams can run lightweight surveys after major releases to track DX trends.
- Designing with developer empathy means treating the API as a product and the developers consuming it as the end-users. This requires shifting complexity from the consumer to the producer, even if it increases the engineering challenge for the internal team. - Effective API error handling involves using standard HTTP status codes, providing descriptive and actionable error messages, and maintaining a consistent error response format across all endpoints. Crucially, error messages should never expose sensitive internal information like stack traces. - The "API-first" design methodology, where teams collaborate on the API design with stakeholders before implementation, helps ensure the API meets consumer needs and workflows. This approach often involves using a specification format like OpenAPI to facilitate discussion and tooling. - At Airbnb, the internal "Minerva API" acts as a unified metric-serving layer, allowing internal data consumers to request metrics and dimensions without needing to know the underlying data storage or computation logic. This simplifies data consumption for a wide range of internal users with varying technical expertise. - Developer Experience (DevEx) can be measured through a combination of quantitative metrics like API response time and qualitative feedback from surveys. Research from LinkedIn's developer productivity team found that developer satisfaction scores have a 0.72 correlation with retention rates. - To improve the developer experience for its internal teams, Airbnb created an Access Control Platform with a strong focus on tooling. They use an asynchronous message queue to notify different systems about permission changes, which simplifies the process of building connectors. - A key aspect of developer empathy is providing high-quality, comprehensive documentation. This includes not just endpoint definitions but also clear examples of requests and responses, as well as documenting common error codes and how to resolve them. - For internal platforms, a low-code, drag-and-drop user interface can be built on top of APIs to empower non-technical teams. At Airbnb, the "Journey Platform" allows users to create event-driven notification workflows through a visual interface that then generates a custom DSL to be executed by the backend.
