Introducing Branch: A VS Code Extension for Visualizing and Testing RESTful Routes
Imagine being able to interact with your entire backend from your coding environment with the click of a button. Welcome to Branch!
Why?
Servers can contain many different routers, routes and endpoints. Navigating all those different endpoints can be a challenge. Also, testing requires leaving your coding environment to open an external API client, and pasting in your strung together route without verification that it even exists within your own application. Once you’ve made your request, those results then live in the other API client, not shared with your coding environment.
Branch offers an easy, digestible way for developers to visualize their server environment in real time as they make adjustments to their own code. Our tool automatically generates a hierarchical tree of all existing routes so there is no need to dig through the server directory to mentally piece together each one individually. The tree is formed just by opening the extension, and once this is complete, checking an endpoint is as simple as clicking on a node. If required, simply input the request body or ID into your URL’s parameter and click the highlighted request button. Once the request finishes, you will see the response data from the server in the response data box.
How does it work?
Under the hood Branch is powered by two unique algorithms that were developed for two specific goals:
- Scrape the clients files looking for traditional RESTful route architecture.
- Format the scraped raw data into a nested JSON object representing a hierarchical path from port to router to each unique endpoint .
The first algorithm spawns a Node.js child process to silently execute shell commands in the user’s workspace. Branch utilizes RipGrep to recursively search the current directory for a variety of regex patterns. This gives Branch the unformatted raw scraped routes.
Before we get into the 2nd algo, let’s talk about why all this is necessary. The key to our extension is the route visualization tool. Branch is able to make that work by utilizing the D3.js javascript library. D3 describes itself as “bringing data to life”. In this case, we can take an entire server directory and use it to build an interactive tree.
The second algorithm Branch relies on then takes the scraped data and formats that into a nested JSON object. This nested object is the key to creating our dynamic tree visualization, and requires a specific key and value structure that is flexible enough to work with any schema.
To achieve the hierarchy:
- We scrape through the server directory to find PORT which will become the parent node in the tree
- We scrape through the router directory to find all children, grandchildren, etc until we have reached the endpoint of each route
- Finally, we append any available methods matching each endpoint
Here is an example portion of our nested object:
Before we get into the tree display functionality of our product, we should mention how all of this content appears within the VS Code window. WebView is different from the browser in that there is no index.html. We use the VS Code WebView API to write HTML and insert our script tags for javascript functionality via the getWebViewContent method.
Once Branch has scraped and formatted the data, then through the VS Code API we pass the nested JSON object as a message to the visualization file using an event listener. The VS Code API prefers data to be passed from file to WebView utilizing the window.postMessage method.
After the tree is formed the user then has the ability to click on nodes and add query params or a request body to test the specific route methods. Under the hood, Branch utilizes DOM manipulation to read the clients inputs and then passes everything to the fetch API. Branch then displays the response data neatly in a code editor, CodeMirror, that gives the user the look of a coding environment.
Supporting RESTful Architecture
You hear about RESTful architecture all the time, but how do you implement it confidently within your application? Branch provides you with the tools you need to ensure that you are making the best decisions in setting up your requests so that they are easy to see and test, all within the same space you are already working. Are you sending back the correct information to the client? Is the database receiving the information properly on each request? Any issues evolving from these questions can more quickly be resolved using Branch to spot necessary changes and tweaks that can make your app run more smoothly and with fewer side effects.
In Conclusion
Branch can save you time and energy by allowing you to visualize and test RESTful routes all in one place, your code editor!
If you want to install the extension, search for Branch in your VS Code Extensions side panel, or click here.
If you are interested in contributing to this open source product, visit our Branch GitHub page to get started!
If you still have questions, please check out our splash page or feel free to reach out to a team member.
Follow the members of Team Branch at the links below:
