Building Harbour's API v2: Foundations and Strategic Decisions

This is Part 1 of a series documenting our journey in building Harbour's API v2. Follow along as we explore key decisions, challenges, and outcomes in modern API design.

Author's Note: As the Senior Software Engineer leading API development at Harbour, I've been at the forefront of our transition to API v2. This series shares our real-world experiences and insights, hoping to contribute to the broader conversation about modern API design.

Series Overview:

• Part 1: Foundations and Strategic Decisions (you are here)
• Part 2: Authentication and Authorization
• Part 3: Resource Design and Modeling
• Part 4: Error Handling and Validation
• Part 5: Performance and Scalability
• Part 6: Developer Experience
• Part 7: Operational Excellence

The Case for Change

Our original API served us well, but as Harbour grew, we encountered several challenges that prompted us to consider a complete redesign:

1. Parallel API Structures: We maintained separate APIs for internal and external use, leading to inconsistencies and increased maintenance overhead.
2. Limited Extensibility: The original design made it challenging to add new features without impacting existing integrations.
3. Evolving Domain Model: As our web application evolved, we introduced new business concepts like workspaces, teams, and fine-grained permissions. Our original API design was built around a simpler model of organizations and users, making it impossible to properly represent these new relationships and access patterns without breaking existing integrations.

Core Design Principles

Rather than making incremental improvements, we decided to build API v2 based on three fundamental principles:

1. Unified API Architecture

Instead of maintaining separate internal and external APIs, we adopted a unified approach. This decision, while seemingly counterintuitive, has proven transformative:

• Consistent Experience: Both internal teams and external developers work with the same interface, eliminating disparities in functionality and behavior
• Improved Quality: Internal usage surfaces issues before they reach customers, as our teams become the first users of any new feature
• Faster Evolution: Changes and improvements benefit all users simultaneously, reducing development overhead and accelerating platform growth

2. Developer Experience First

We prioritized developer experience in every aspect of the API design, focusing on making integration intuitive and debuggable:

• Clear Error Context: Every error response includes actionable information, complete with request IDs, documentation links, and suggested solutions
• Self-Service Integration: Developers can generate their own API keys, access interactive documentation, and test in sandboxed environments
• Immediate Feedback: Real-time validation and detailed responses help developers understand exactly what's happening with their requests
• Contextual Documentation: Every API response includes relevant links to documentation, making it easy to learn while building

3. Future-Proof Design

We built API v2 with evolution in mind, implementing patterns that allow our API to grow alongside our product:

• Resource-Level Versioning: Each resource can evolve independently, allowing us to update critical endpoints without forcing all clients to migrate
• Backward Compatibility: New features are introduced additively, ensuring existing integrations continue to work while enabling gradual adoption
• Extensible Architecture: Built-in support for metadata, capability discovery, and relationship modeling allows us to add functionality without breaking changes

These principles work together to create an API that's not just powerful, but also pleasant to use and built to last. The results speak for themselves: faster integration times, reduced support burden, and higher developer satisfaction scores.

Implementation Challenges and Solutions

Authentication and Authorization

We implemented a multi-layered approach:

• API keys for simple integrations
• OAuth 2.0 for service-to-service communication
• ReBAC (Relationship-Based Access Control) for fine-grained permissions

Resource Modeling

We adopted a consistent approach to resource naming and relationships:

/organizations/{org_id}/projects/{project_id}/tasks        

This hierarchical structure:

• Reflects natural business relationships
• Provides clear context for resources
• Enables intuitive navigation of the API

Query Design

We implemented a flexible query parameter system:

GET /api/v2/projects?status=active&order_by=-created_at        

This allows clients to:

• Filter data efficiently
• Control response payload size
• Reduce unnecessary data transfer

Lessons Learned

Unified APIs Are Worth the Complexity

• Initial setup requires more thought
• Long-term benefits outweigh implementation challenges
• Creates a better development ecosystem

Design for Evolution

• Plan for change from the start
• Build in extensibility mechanisms
• Document design decisions and rationale

Developer Experience Matters

• Clear, consistent patterns reduce integration time
• Good documentation is as important as good code
• Real-world usage drives meaningful improvements

Looking Ahead

This foundation sets the stage for more advanced features we'll explore in upcoming articles:

• Advanced authentication and authorization patterns
• Sophisticated resource relationships
• Performance optimization techniques
• Real-time capabilities

As we continue building and refining API v2, we're already seeing the benefits of these foundational decisions. In the next article, we'll dive deeper into our authentication and authorization implementation, exploring how we balance security with usability.

Stay tuned for Part 2 of this series, where we'll explore how we implemented our multi-layered authentication system and the lessons learned along the way.