Passages Rails Engine
03 Jan 2016
Routing in the Ruby on Rails world can, at times, be a tad confusing. The official Rails guide is very helpful for the basics; but, as an application grows, it can become hard to remember specific details about every single route.
Existing Routing Tools
To remedy the issue of route complexity, a few helpful tools already exist. The most useful one is rake routes, which can be executed in the working directory of a Rails application. This tool requires that the application be on the developer’s local system, which is fine for applications that a developer owns, but what about services that the developer does not own?
While this problem might not exist for everyone, chances are at least one poor software engineer has been slapped in the face with a 404 page and shouted: “I know that route exists! Why doesn’t this work?”
Another helpful tool in development mode is this screen:
This page provides the ability to enter search terms that match words in the paths of specfic routes. However, similarly to rake routes, this screen is only accessible in development mode. While this tool is still extremely useful, there could be cases when route inspection would be helpful without running the server locally.
New Hotness
The Passages Rails Engine was created to fulfill two main purposes:
1. To expose routes of a Ruby on Rails application either during or outside development mode.
2. Enable searching on multiple pieces of a route’s information (HTTP verb, controller, path, etc).
Some might wonder by 1 would even be valuable. Imagine for a moment that a team of engineers decides that they need an internal API to power their various applications. Perhaps while developing this API, some basic documentation is written but never actually kept up to date. Maybe the API changes so fast that documentation just falls behind.
Whatever the reason, it becomes laborious for the consumers of that internal API to constantly ask which route does what and which parameters are expected in each URL.
Internal APIs are not the only candidate for Passages. An external API can also benefit from discoverable routing in lieu of or in addition to documentation. Since Passages has the option to use HTTP Basic Authentication, securing Passages is as simple as setting two ENV variables.
Purpose 2 is an attempt to reduce a large application’s route pile by expanding each route’s search surface area. A user of Passages might want to know of all the PUT routes or routes that map to a destroy action. Like its predecessor, Passages' route path search is also extremely valuable.
With (hopefully) the help of the open source community, the types of useful search features for Passages will expand from these very humble beginnings.
Demo
After following the installation guide from the project’s README, A very basic use of Passages would look like:
Contributing
Like most Open Source projects, Passages has many areas that welcome modification. Specifically, the design and search functionalities are suitable candidates for enhancement.
Please feel free to fork the repository or create an issue on Github if something seems wrong or out of place.
Currently, Passages only supports Ruby on Rails 4. It will most likely be upgraded when Ruby on Rails 5 is released but there are no plans to support Ruby on Rails 3 or older.