Passages Rails Engine03 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.
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
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.
After following the installation guide from the project’s README, A very basic use of
Passages would look like:
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.
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.