# 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://jranjan.destinjidee.com/blogs/api-ecosystem/the-puzzle-api-first-vs.-refactor-first.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.