Engineering

The Fragmentation in API Tooling: Specialized Tools, Inefficient Processes

Navigating the API tooling space can be an adventure. One of the main reasons is the fragmentation of so many tools. In response to that, ApyHub aims to unify the API lifecycle by integrating design, documentation, testing, and publishing into one platform, enhancing collaboration and efficiency for all stakeholders involved in the API lifecycle.
The Fragmentation in API Tooling: Specialized Tools, Inefficient Processes
SA
Samuel Kaluvuri
Last updated on July 16, 2024
The API management world is certainly a difficult one to navigate, especially for beginners. I can tell from my own experience that the number of tools that are out there and available is quite staggering. Most of these tools have been created in order to challenge the status quo that exists and claim to be the “ultimate solution”, promising to replace the ubiquitous Postman. I will not go into detail here on what is wrong with Postman - developers have their own (strong) opinions and the existence of so many API tools kind of proves this statement. Some nice articles I think are relevant:
I took a close look and tried to make a good analysis and inspection of some of these API tools. What I found is that most of them have a kind of narrow focus - they main focus areas tend to be API testing and the where the data is stored for the API collections, whether in the cloud, git repositories, or local files. However, I do think that this narrow focus approach kind of neglects the much broader scope of API management. You see, API management includes API design, API documentation, and API publishing.
A bit of a background on why I did this analysis: At ApyHub we have more than 100 APIs that are publicly available, and a few hundreds more internal APIs that power our platform. As you can imagine we had to really perfect our API management game to ensure proper documentation, broad test coverage, collaboration around API design among others. The fragmented nature of the API tooling made our processes very inefficient and created numerous challenges.

The Fragmentation Problem

API management is a multifaceted discipline - Therefore relying solely on tools that emphasise testing while neglecting other critical aspects (such as design, documentation, and publishing) can lead to several problems. Let's consider the following aspects of an API lifecycle:
  • Design: Crafting the structure and behavior of APIs.
  • Testing: Ensuring that the APIs function as expected under various cases and conditions.
  • Documentation & Publishing: Creating clear, user-friendly guides and references for API consumers (both internal and external).
  • Monetizing: Being able to monetize your APIs with all the required controls (rate limting, authenticaiton, authorization, subscription management etc).
Each of these components is by itself crucial for the successful deployment and utilization of APIs. However, when teams use different tools for each of these tasks, (such as SwaggerHub for design, Confluence for documentation, ReadMe for user guides, Stoplight for design and documentation, and endless copy-pasting of cURL commands on Slack or teams) the process becomes disjointed and cumbersome.
I don't mean to say that these tools are bad or wrong. The opposite. I have used and liked most of them. The problem lies with the integration, their fitting into the big(ger) picture. But since we are on the topic, let's have a look at the different tools available for the different aspects of an API lifecycle.

Overview of Tools by API Lifecycle Phase

Design Phase

Tools: SwaggerHub, Stoplight, Apicurio
  • SwaggerHub
    • Pros:
      • Supports OpenAPI standards
      • Some collaborative features
      • Integrates with various CI/CD pipelines.
    • Cons:
      • Can be complex for beginners
  • Stoplight
    • Pros:
      • Visual interface for designing APIs
      • Supports OpenAPI and JSON Schema
    • Cons: Limited offline capabilities
      • Some users have reported performance issues with large projects.
  • Apicurio
    • Pros:
      • Open-source
      • Integrated with Red Hat's ecosystem
      • Strong version control.
    • Cons:
      • Steeper learning curve
      • Fewer features compared to commercial alternatives.

Testing Phase

Tools: Postman, Insomnia, Bruno, Karatelabs
  • Postman
    • Pros:
      • Comprehensive testing features
      • Community support.
    • Cons:
      • Can be resource-intensive
      • Sort of many features/bloated
      • Many add-ons - Premium features can be expensive.
  • Insomnia
    • Pros:
      • Lightweight, intuitive interface
      • Great tool for quick testing.
    • Cons:
      • Has limited features for API testing when compared to Postman
      • Limited collaboration features.
  • Bruno
    • Pros:
      • Local Collection Storage
      • Bru Markup Language
      • Git Collaboration
    • Cons:
      • Limited collaboration: Since it is based on Git flows, there is no easy way to enable discussions, and real time collaboration around API design.
      • No OpenAPI spec design capabilities

Documentation & Publishing Phase

Popular Tools: Confluence, ReadMe, Slate
  • Confluence
    • Pros:
      • Great for internal developer documentation
      • Integrates well with other Atlassian tools, and robust search functionality.
    • Cons:
      • Not specialized for API documentation, can be overkill for smaller teams.
  • ReadMe
    • Pros:
      • Designed specifically for API documentation, easy to use.
      • Supports API key generation.
    • Cons:
      • Kind of expensive for small teams.
      • Limited customization options.
  • Slate
    • Pros:
      • Open-source, clean, and responsive design, Markdown-based.
    • Cons:
      • Requires setup and hosting, less intuitive for non-technical users.

Monetising Phase

Tools: Rapid, API Layer
  • Rapid
    • Pros (for API providers):
      • No barrier to add an API
    • Cons (for API consumers):
      • No Curation - Anyone can publish their API
      • Different subscriptions for using different APIs
  • API Layer
    • Pros (for API providers):
      • No easy way to publish
    • Cons (for API consumers):
      • Different subscriptions for using different APIs

Challenges of Fragmented API Tooling

Despite the many pros for each tool, the main challenge I see is that ultimately companies need to use many of them at the same time for different purposes. The use of different tools for API management leads to several issues:
  1. Broken Processes: When tools don't integrate seamlessly, the API-related workflows become disjointed. Information then has to be manually transferred between tools, increasing the risk of unwanted errors and omissions.
  2. Confusion: Different team members may prefer or require different tools. Trying to accommodate these different needs can result in a lack of standardization. This diversity can cause confusion, especially when onboarding new team members or collaborating across departments.
  3. Frustration: Inefficiencies and misunderstandings can lead to frustration among team members. Developers, QA specialists, Technical Writers, and API consumers often have different needs and priorities. A fragmented tooling environment fails to cater to these diverse requirements effectively.

The Need for Integrated API Management Tools

For API management to be truly effective, tools need to facilitate a (real) seamless collaboration and offer role-specific capabilities. An ideal API management tool should cater to the needs of various stakeholders, such as:
  • QA Teams: Require robust testing features and easy access to all test cases and results.
  • Developers: Need efficient design and debugging tools integrated with their workflow.
  • API Consumers: Look for clear, comprehensive documentation and reliable API support.
  • Technical Writers: Need intuitive documentation tools that can easily integrate with design and testing processes.

ApyHub: A Comprehensive Alternative

The inefficiencies mentioned above have been the main drivers for us to keep working on the ApyHub Platform. We started with the catalog, enabling API consumers to browse and discover APIs for their applications. Later, we built Fusion which focuses on building, testing, and documenting the APIs: We want to be a realistic and robust alternative to Postman, addressing the fragmentation problem by unifying the essential components of API management into a single platform. To give some context, we wanted Fusion to offer:
  • Designing, Testing, and Documenting APIs all in one place: Fusion is an all in one tool/ecosystem that accommodates all the phases of the API lifecycle. Fusion can be used by developers to design and build awesome APIs, by Technical Writers to document them, and by QA teams to Test them. Finally, it can be used to publish the APIs both internally but also externally (with the option to monetize them).
  • Real-Time Collaboration across all stages in the API lifecycle: Fusion allows multiple team members to work on API design, testing, and documentation simultaneously, ensuring everyone is on the same page.
  • Modular API Design: Provides flexibility in designing APIs, accommodating various complexity levels and use cases.
  • Self-Hosted Options: Ensures data ownership and security by allowing organizations to host Fusion on their own servers.
  • Intuitive User Experience: Focuses on a user-friendly interface that simplifies complex tasks, making API management more intuitive and less frustrating.
apy-fusion.png

Conclusion

The fragmentation of API tooling is a significant challenge for many teams, leading to inefficiencies and frustrations. By integrating design, documentation, testing, and publishing into a unified platform, Fusion offers a comprehensive solution that enhances collaboration, streamlines processes and caters to the needs of all stakeholders involved in API management. Adopting such an integrated tool can transform API management from a fragmented, inefficient process into a seamless, productive experience.