Overview

My contributions to Asana’s API ecosystem spanned 2022-2023, focusing on:

• Vision: Designing long-term API strategy
• Technical Leadership: Creating frameworks and automation
• Implementation: Building tools and scripts
• Consulting: Enabling teams to ship successfully

Timeline of Contributions

2022: Foundation Year

Project Launch

• Joined API initiative at Asana
• Identified key pain points:
  • Manual OAS writing (error-prone, time-consuming)
  • Inconsistent documentation
  • Slow client library generation
  • No systematic change management

Q2 2022: OAS Revolution Begins

Key Initiative: OAS-Driven Development

Proposed fundamental shift in API development:

• OAS as single source of truth
• Automated generation from code
• Eliminated manual errors
• Faster time-to-market

OAS Vision: From Chaos to Order

Current State (2022)

Engineers → Manual OAS → Errors → Delays
DevRel → Manual Updates → Inconsistencies
Developers → Confusion → Poor Experience

Target State

Engineers → Code → Auto-Generated OAS
OAS → Documentation + Client Libraries + API
Developers → Consistent Experience

Q2 2022: Technical Proposals

Scala-Built OAS Proposal

• Leverage declarative Scala API framework
• Auto-generate OAS from code
• Key insight: Our API was already declarative!
• Proposed strangler pattern for gradual migration

Q3 2022: Change Management Framework

Launched API Change Management Program

Pain Points Addressed:

• Unpredictable API deployments
• Breaking changes without warning
• No systematic review process
• Poor communication with developers

Q3 2022: Technical Implementation

Built Core Infrastructure

• OAS validation and linting tools
• Automated client library generation pipeline
• Testing framework for generated libraries
• Scripts for OAS transformation

Q4 2022: AOR Establishment

API Change Shepherd Role

Responsibilities:

• Guide teams through Change Framework
• Design rollout strategies
• Mediate producer/consumer needs
• Ensure OAS accuracy

Q1 2023: Program Maturation

Change Program Formalization

Key Results:

• Established review process
• Created deployment predictability
• Improved developer communication
• Reduced breaking changes

March 2023: PADM Relaunch

Developer Communication Milestone

• Relaunched Platform API Developer Management
• Improved forum engagement
• Better change announcements
• Stronger developer relationships

Technical Deep Dive

Problem: Manual OAS Hell

# Before: Engineers manually writing OAS
# Result: Errors, inconsistencies, delays

paths:
  /workspaces/{workspace_gid}/users:
    get:
      # Manually maintained = often wrong
      # Out of sync with actual API

Solution: Automated Generation

// Scala API already declarative
buildRoute(
  path = "/workspaces/:workspace/users",
  method = GET,
  handler = WorkspaceController.getUsers
)

// ↓ Auto-generates ↓

// Accurate OAS, always in sync

Technical Contributions

1. OAS Transformation Pipeline

• Scripts to transform and validate OAS
• Automated error detection
• Consistency checks
• Version management

2. Client Library Automation

# Automated pipeline
OAS → Generate Libraries → Run Tests → Deploy

# Key achievement:
# Reduced library generation from days to hours

3. Change Framework Implementation

Response Header Enhancement

Asana-Change: name=new_custom_field_values;
              info=something;
              enabled=true

Added enabled=true to help clients determine effective behavior

4. Validation Improvements

Before: Missing enum values, type mismatches After: Automated validation catches issues early

Example fix:

# Added missing 'people' to Custom Field type enum
enum: ["text", "number", "people", ...]

Consulting Impact

API Producer Support

• Office hours for API teams
• Guided 20+ teams through changes
• Created documentation templates
• Established best practices

Success Outcomes

Developer Experience

• Faster client library updates (days → hours)
• Automated OAS generation eliminated manual errors
• Improved developer communication through forum engagement

Engineering Efficiency

• Eliminated manual OAS writing process
• Automated validation caught issues early
• Supported 20+ teams through API changes

Strategic Vision: 4-Phase Evolution

Phase 1: Charon (Foundation)

• Manual processes documented
• Basic validation tools

Phase 2: Tartarus (Automation)

• Automated OAS generation
• Client library pipeline

Phase 3: Asphodel (Integration)

• Full CI/CD integration
• Real-time validation

Phase 4: Elysium (Perfection)

• Fully automated ecosystem
• Self-documenting APIs
• Zero manual intervention

Key Challenges Overcome

Technical Challenges

1. Scala naming vs API naming

   • Solution: Interface for OAS-name mapping
   • Validation against existing OAS

2. Gradual migration

   • Solution: Strangler pattern
   • Incremental adoption

Organizational Challenges

1. Developer resistance

   • Solution: Show immediate value
   • Provide high-touch support

2. Cross-team coordination

   • Solution: Change Framework
   • Clear ownership model

Business Impact

Documented Outcomes

• Process Improvement: Eliminated manual OAS writing
• Speed: Client library generation from days to hours
• Quality: Automated validation prevented errors
• Scale: Supported 20+ engineering teams through changes

Strategic Outcomes

Before

• API as bottleneck
• Manual, error-prone processes
• Poor developer experience

After

• API as accelerator
• Automated, reliable systems
• Delightful developer experience

Relevance to Stainless

Direct Alignment

My Asana work directly relates to Stainless’s mission:

1. OAS Expertise: Deep understanding of OpenAPI specifications
2. SDK Generation: Built automated client library pipelines
3. Developer Experience: Passionate about API usability
4. Technical Leadership: Drove organization-wide transformation

Transferable Skills

• Vision: Can see beyond immediate problems
• Execution: Deliver complex technical projects
• Influence: Guide teams without authority
• Quality: Obsessive about correctness

Lessons Learned

What Worked

1. Incremental approach: Strangler pattern for gradual adoption
2. Developer-first: Focus on API consumer experience
3. Automation: Eliminate manual processes wherever possible
4. Measurement: Track impact quantitatively

What I’d Do Differently

1. Earlier stakeholder buy-in: Engage executives sooner
2. More aggressive timeline: Could have moved faster
3. Better documentation: More examples and tutorials
4. Broader scope: Should have included GraphQL earlier

Future Vision

For Stainless

I see opportunities to:

1. Enhance SDK quality: Apply validation learnings
2. Improve generation speed: Optimize pipelines
3. Better developer tools: IDE integrations, debugging
4. Expand capabilities: GraphQL, gRPC, AsyncAPI

Questions?

Thank you for considering my experience transforming Asana’s API ecosystem.

I’m excited to discuss how these learnings can benefit Stainless and its customers.

Backup Slides

Technical Details: OAS Generation

// Declarative API definition
case class GetUsersRequest(
  workspace: WorkspaceGid,
  limit: Option[Int],
  offset: Option[String]
)

// Auto-generates OAS:
paths:
  /workspaces/{workspace_gid}/users:
    parameters:
      - name: limit
        in: query
        type: integer

Change Framework Example

# change_manifest.yaml
- name: new_custom_field_values
  description: New representation for custom fields
  rollout:
    start: 2023-01-15
    stages:
      - percent: 1
        date: 2023-01-15
      - percent: 10
        date: 2023-01-22
      - percent: 100
        date: 2023-02-01

Client Library Testing

#!/bin/bash
# Automated testing pipeline

# 1. Generate libraries from OAS
generate_libraries $OAS_FILE

# 2. Run language-specific tests
for lang in python javascript ruby java; do
  run_tests $lang
done

# 3. Validate against live API
validate_against_production

Consulting Artifacts

• API Design Guidelines: 50-page best practices document
• Change Checklist: Step-by-step guide for API changes
• OAS Templates: Reusable patterns for common endpoints
• Training Materials: Workshops for engineering teams