Episode 542: Brendan Callum on Contract-Driven APIs

Approach Overview

Brendan Callum, engineering manager for Pinterest's developer platform team, introduces the spec first approach to API development. Unlike the API first strategy, which is a product philosophy, spec first is a tactical method ensuring APIs align with product goals and maintain high quality. This approach organizes development processes to deliver consistent and reliable APIs, crucial for scaling products effectively 1.

Spec first is one way to organize the process of development to ensure those kinds of outcomes.

--- Brendan Callum

This method emphasizes the importance of aligning API development with product objectives from the outset.

   

Design Consistency

The spec first approach significantly enhances API design consistency by focusing on the client's experience before backend logic. Brendan explains that starting with the API's consumer perspective ensures standardization and predictability across endpoints 2. This method addresses past inconsistencies where different endpoints had varying design patterns, causing confusion among developers.

What they're really asking for was consistency, predictability, and not having lots of undocumented changes that cause them to thrash and break their apps.

--- Brendan Callum

By prioritizing the spec, Pinterest has achieved a more flexible yet consistent API design, accommodating new creative formats and analytics frameworks 3.

   

Implementation Challenges

Implementing the spec first approach presented challenges, particularly in maintaining consistency across diverse API endpoints. Brendan highlights the tension between designing for specific use cases and ensuring overall API uniformity 4. A rotating review group was established to address these challenges, ensuring partner-centric consistency reviews.

There's definitely a healthy tension between maximum consistency across the entire API surface versus designing like a single endpoint for a very specific use case.

--- Brendan Callum

Additionally, migrating partners to new API versions required careful planning to maintain feature parity and ease the transition 5.

   

Development Insights

The launch of Pinterest's V5 API, using the spec first approach, has provided valuable insights both internally and externally. Brendan notes that the API's predictability and ease of use have significantly increased developer engagement and daily active usage 6. Internally, the adoption of tools like IDE plugins and linters has streamlined the development process, embedding best practices directly into the workflow.

Bringing the best practices and the guidance into real, concrete, actionable rules for developers has been huge.

--- Brendan Callum

These tools have facilitated learning and ensured adherence to standards, reducing the need for extensive code reviews.