API Sidebar: Show Request Count Badges

by Alex Johnson 39 views

In the world of API development, organization and quick comprehension are paramount. When you're juggling numerous API collections, each potentially containing a myriad of requests, the sidebar becomes your primary navigation tool. However, as it stands, this crucial area often lacks the immediate visual cues that developers need to efficiently manage their workspaces. This article delves into a compelling feature request: adding a request count badge to collection folders in the sidebar. We'll explore the motivation behind this enhancement, the current limitations, the desired behavior, and how you can help test this exciting development.

The Motivation: Streamlining Your API Workspace

Imagine diving into your API client, faced with a sidebar brimming with collection folders. Users need to quickly understand the scope and organization of their workspace. Currently, these folders present themselves with just a name and an icon. While functional, this minimalist approach falls short when dealing with extensive API collections. There's no immediate way to gauge the density or activity within each folder. Are you looking at a highly active collection with dozens of requests, or a sparsely populated one that might be a relic or a placeholder? Without a visual indicator, you're left to manually expand each folder, a process that quickly becomes tedious and inefficient, especially with a large number of collections. This friction hinders rapid assessment, making it difficult to spot actively used collections, identify empty ones that might need cleaning up, or even understand which folders might require reorganization. Adding a count badge to display the number of requests in each collection would significantly improve the user experience by providing immediate visual feedback about collection size. This small addition can make a substantial difference in how users interact with and manage their API projects, leading to a more productive and less frustrating workflow. It's about providing context at a glance, empowering developers to make informed decisions about their API structure without unnecessary clicks.

Current Behavior: A Sidebar Lacking Context

Let's talk about the reality of the current API client sidebar. Collection folders in the API Client sidebar display only the folder name and icon. This means that no matter how many requests are nestled within a folder, the sidebar remains blissfully unaware, presenting a uniform appearance across all collections. Users must expand each folder to see its contents and cannot tell at a glance how many requests are contained within each collection. This forces a manual exploration for even the most basic understanding of a collection's scope. To illustrate this, consider these simple reproduction steps:

  1. Open the Scalar API Client: Launch the application to access your API collections.
  2. Create multiple collections with varying numbers of requests: Start by creating a few distinct folders. Populate one with a single request, another with two or three, and crucially, create at least one folder that remains completely empty. This variation is key to observing the limitations.
  3. Look at the sidebar where collections are listed: Direct your attention to the left-hand pane where your organized API collections reside.
  4. Observe: Only collection names and icons are visible: You'll notice that each collection folder is represented solely by its designated name and its associated icon. There are no numerical indicators or any other visual cues to suggest the quantity of items within.
  5. Note: There is no visual indicator of how many requests each collection contains: This is the core of the issue. You are left to guess or investigate further, highlighting the lack of immediate, actionable information.

This behavior, while functional on a basic level, creates a significant usability bottleneck for anyone working with more than a handful of API collections. It transforms a potentially powerful organizational tool into a static list, requiring extra effort for even simple task like identifying the most populated or least utilized sections of your API project. The absence of this simple count badge means that understanding your API landscape requires more effort than it should, impacting efficiency and potentially leading to missed organizational opportunities.

Expected Behavior: Contextual Clarity with Badges

Now, let's envision the improved experience. Each collection folder in the sidebar should display a small badge showing the number of requests it contains. This isn't about cluttering the interface; rather, it's about providing contextual clarity with badges that are both informative and unobtrusive. The badge should be visually distinct but not overwhelming, positioned near the collection name. This placement ensures it's easily noticeable without distracting from the folder's title. For collections that are empty, meaning they contain zero requests, there are a couple of thoughtful approaches. They might show no badge at all, subtly indicating their emptiness, or alternatively, display a "0" if the design team prefers a consistent presence of the badge element across all folders. The key is that the presence or absence of a badge, or its displayed number, immediately communicates the contents of the folder at a glance.

To ensure this feature is implemented perfectly, we have defined clear acceptance criteria:

  • [ ] A badge displaying the request count appears next to each collection name in the sidebar: This is the primary visual change we expect to see. It should be a persistent element in the sidebar view.
  • [ ] The count accurately reflects the total number of requests in the collection (including nested folders): This is crucial for accurate representation. The count must be comprehensive, summing up requests not just in the top-level folder but also those contained within any sub-folders.
  • [ ] The badge updates dynamically when requests are added or removed: As users modify their collections, the badge must reflect these changes in real-time, ensuring the information is always current and reliable.
  • [ ] The badge styling is consistent with the application's design system: The new element should feel like a natural part of the UI, adhering to the established visual language of the API client for a cohesive user experience.
  • [ ] Empty collections either show no badge: This addresses the specific UI consideration for folders devoid of requests, ensuring a clean and informative display.

This enhanced behavior transforms the sidebar from a static list into an interactive, informative dashboard, empowering developers with the information they need, precisely when and where they need it. It's a significant step towards a more intuitive and efficient API development environment.

Steps To Test: Your Role in Shaping the Feature

This is where you come in! Your feedback and testing are invaluable in ensuring this feature is robust and meets the needs of the API development community. We've outlined clear steps to test the new request count badge functionality. Follow these instructions carefully, and report any discrepancies or suggestions. Your participation is crucial for a polished final product.

  1. Start the API Client with pnpm dev:client: This command initiates the development version of the API client, allowing you to test the latest changes before they are merged into the main release. Ensure you have the necessary development environment set up.
  2. Create a new collection and add 3-5 requests to it: Begin by setting up a test scenario. Create a fresh collection folder and populate it with a small, manageable number of requests. This provides a baseline to observe the badge's appearance.
  3. Verify a badge appears showing the correct count: Once the requests are added, meticulously check the sidebar. A badge should now be visible next to your new collection's name, and the number displayed should accurately match the number of requests you just added.
  4. Add another request and verify the count increments: Continue by adding one more request to the same collection. Observe the badge again. It should now reflect the updated total, demonstrating that the count increases as expected.
  5. Delete a request and verify the count decrements: To test the removal functionality, delete one of the requests you previously added. Check the badge one last time. The number should decrease by one, confirming that the count accurately reflects deletions.
  6. Create a collection with nested folders containing requests and verify the count includes all nested requests: This is a key test for comprehensive counting. Create a main collection, and within it, create one or more sub-folders. Add requests to these sub-folders. The badge on the main collection folder should display the total number of requests across all its nested sub-folders, not just those directly within the main folder itself.
  7. Create an empty collection and verify it shows no badge: Finally, create a new collection folder but do not add any requests to it. Observe the sidebar. According to the expected behavior, this empty collection should not display a badge, indicating its lack of content clearly.

Submission: Share Your Findings!

Once you've completed the testing, we need you to share your experience. To provide the clearest possible feedback, we encourage you to record your testing session. Download https://cap.so/ to record your screen (use Studio mode). Export as an mp4, and drag and drop into an issue comment below. A video demonstration is incredibly helpful for developers to quickly understand any issues you encounter or to see the feature working as intended. Your detailed observations, especially when accompanied by a visual recording, will directly contribute to the refinement and successful implementation of this valuable feature.

For those interested in contributing further, please refer to the Guide to submitting pull requests: https://hackmd.io/@timothy1ee/Hky8kV3hlx. This guide provides comprehensive information on how to submit your code changes if you wish to contribute directly to the development process. Your engagement makes our tools better for everyone.

For further reading on API design best practices and efficient tooling, consider exploring resources from organizations like the Postman Blog.