Quantifying The Value of good Software Architecture is difficult

I was asked by a colleague for some advice in designing a new service. They are collaborating with another team and when they started looking at the documentation provided, they had noticed that most parameters were being passed in the path rather than the body. This is, despite it being a POST method. They had asked me if they saw any problem with this.

My answer; not really, but yes. Not really, because in this case there was no PII, and it was data being passed between two internal services. The number of parameters was also small and their length was unlikely to be an issue (two UUIDs and an int). And then there is a binary file which will also come along in the body.

However, I circled back on that and said "if you have any say in the matter, push back and go for taking the parameters in the body". Why? 2 reasons. First, they had plans to expose this API to the public at a later date, even if that isn't the intended target and second, designs are rarely static. Software is a process of feature accretion, not evolution as we tend to state. We slap layer upon layer of feature upon our foundation. The less suited the application is to each successive layer, the more tech debt we gain and the less agile the product becomes. 

Here, consuming parameters in the body is better because, not only is there already a payload in the body to start, but even if these fields aren't PII, independent audits could flag them as leaking sensitive data which could jeopardize business down the road, even if they don't actually represent vulnerabilities. If Company X mandates that you pass security audit XYZ and you fail, it often does not matter how legitimate the concerns are. So, putting the data in the body means it is encrypted over HTTPS which reduces risk.

Another problem is consistency. It is quite likely that the service will grow to include other POST endpoints down the road. And eventually you'll run into one where you can't use the path to consume the parameters (too long, complex type, actually is sensitive data, etc...). Now you need a whole new approach for a subset of the functionality and your codebase is no longer consistent. You also had to solve the problem of how to write a POST method twice. Your API also looks disorganized piece of junk to any external observer. You can write that off as subjective, but as with the security audits, it can hurt you business. 

Software generally only progresses down one path at a time architecturally. And because of this, it is hard to know how things would have gone had we chosen another path. Which is to say, it is VERY hard to quantify the value of good vs. bad software architecture. If it takes more time to do the right thing and the only gain is that it saves you from losing deals in a particular audit, but that audit may never happen, is it still worth doing?

Or, how can you know that doing it right will make future development faster and help maintain the development pace longer? We always notice when things go wrong. By contrast, it is easy to not even notice that the business was able to quickly and easily add a feature because the architecture had supported it or even anticipated it. And that is where the real difficulty lies. Good architecture goes on to define the baseline performance of a team and the intangibles which aren't often discussed in sales. If you've been in the industry long enough, you know that it DOES make a difference. You may even know it makes a huge difference. However, you likely couldn't put a number to it.

At the end of the day, it is always the most efficient to make a good architecture decision early on. If you're ever in a project during the earlier phases, this is definitely the time to push the hardest for improvements. Also, keep notice of any cases which went way over budget due to poor architecture decisions. Especially if you CAN quantify how much quicker and easier the project would have been with a better foundation. Most stakeholders understand numbers, but they often want "real" numbers. Anything you can provide to back up your cases will strengthen it.