The Puzzle: API-First vs. Refactor-First

API-first is a trending approach, and everyone seems eager to implement the best API of their life. While there is plenty of content on API sprawl and its remediations, this draft is a brief account of my professional experience on the topic and how we tackle it on a day-to-day basis.

The Problem: API Sprawl in Enterprises

Have you ever encountered the following questions or statements during a new API use-case discussion?

• Do we have anything existing?

• Where can we find it?

• The existing API can’t be used because it doesn’t support the required request construct, authentication mechanism, or data-sharing constraints

• Reusability is limited—the API was designed for a specific project and doesn’t support cross-domain or cross-team usage

• Our business logic is different and requires a new setup

• The response is missing fields needed for the new use case

• We can’t modify the existing API because it would incur extensive integration and functional testing efforts

• And the list goes on...

To make things more complex, product managers often step in with tight timelines, labeling these issues as urgent requirements.

The Outcome

• 90% of the time: We end up designing a brand-new API, closing the requirement with only 70% functionality match to what was truly needed. This contributes heavily to API sprawl

• 10% of the time: We manage to convince teams to refactor existing APIs instead of creating new ones

Approaches to Control API Sprawl

As architects, one of our key challenges is reducing API sprawl while maintaining flexibility. Some key strategies we’ve adopted include:

1. Design Best Practices

• Focus on generic resources within APIs, using flexible naming and optional parameters.

• Relax data mapping and schema constraints where possible.

• Adopt versioning strategies to avoid breaking changes.

• Ensure standard OAuth 2.0 support for authentication and authorization.

2. Implementation Strategies

• Follow a robust branching strategy to facilitate collaborative contributions.

• Use the Backend-for-Frontend (BFF) pattern for better separation of concerns.

• Maintain a regression test suite to support API evolution.

3. Release & Monitoring

• Leverage containerization for portability and scalability.

• Automate deployments using CI/CD pipelines for smoother releases.

• Implement proactive alerting and monitoring setups to track API performance.

• Support staggered releases to minimize disruptions.

Final thoughts

The real challenge is reducing that 90% outcome, where we default to building new APIs. API-first is a great approach for greenfield projects, but in brownfield environments or business-as-usual (BAU) scenarios, the strategy should be a blend of API-first and Refactor-first.

By taking the right contextual approach, enterprises can achieve true API reusability and significantly reduce API sprawl—leading to a more efficient and maintainable API ecosystem.