Conventions over Configurations

I remember when Ruby on Rails came out some 10+ years ago. It turned the entire software industry on its head, and Microsoft among others spent huge amounts of energy on playing catch up for a couple of years with .Net Framework, creating their (in) famous MVC framework. However, the largest piece of innovation RoR gave us, had nothing to do with frameworks, libraries, or toolset - It was a simple mindset, embodied in the header of this article. I try to apply this mindset everywhere I can. In Magic for instance, if you wrap a database table in CRUD endpoints, you get the exact same URL, API and structure.

• /magic/modules/database/table GET becomes read endpoint
• /magic/modules/database/table PUT becomes update endpoint
• /magic/modules/database/table POST becomes create endpoint
• /magic/modules/database/table DELETE becomes delete endpoint
• /magic/modules/database/table-count GET becomes count endpoint

Notice how all the above URLs are the exact same, except the "count" endpoint, having a trailing "-count". If I wrap the database foo's table bar in a CRUD endpoint for instance, my URLs becomes "/magic/modules/foo/bar". In addition, all endpoints further obeys by dozens of additional "standards". For instance, all read endpoints all have the following common query parameters.

• order
• direction
• limit
• offset
• operator

This implies that once I've taught myself how one read endpoint works, I have effectively taught myself how all read endpoints works. This allows me to reuse not only code that consumes my endpoints, but also in fact the documentation for my endpoints, allowing anyone to easily pick up the HTTP REST internals of Magic in minutes. Overriding individual endpoint URLs and query parameters is possible, but I suspect few will do this, since the above structure is the default structure Magic gives you out of the box. This has a lot of advantages over "configuration", implying if I allowed for individual users to configure their endpoints URLs and API. One advantage is that it significantly reduces the cognitive load and learning requirements down to literally ZERO. Compare that to something such as the following, which is arguably the opposite direction.

The above screenshot is how Microsoft office looks like if you turn on every single toolbar. Do you even know what 50% of those buttons are doing? Microsoft Office is a "configuration over conventions" type of product, and the above is the natural consequences of "configuration madness".

As developers we have a million things to think about that we must keep in our head at the same time - If we allow for too much configurations in our systems, our users becomes baffled, and even learning one instance of our system, doesn't necessarily transition into understanding the next instance of the exact same system. For a noob software developer, having the ability to configure all parts, might be imagined as "flexibility", while it's really just "organised systematic confusion".

Use more conventions and less configuration please

Because flexibility is (often) not a good thing! To give you an idea of how and why, imagine if the HTTP standard allowed for individual developers to "configure" what verbs they want to use, resulting in that system A would use "RETRIEVE" instead of "GET", system B would use "FETCH", and system C would use "HENTE" (Norwegian verb for GET)

If the HTTP standard was created around "configurations instead of conventions", I suspect the World Wide Web would have ended up having 5 users instead of 5 billion as it does.