Shifting complexity? Really? Let’s say that login method has 500 references. So you need to add lastLoggedIn. That’s 500 changes. Then they need another parameter. That’s another 500 changes. Need to change a parameter type? Wow, another 500 changes please. Or you could just put it on a class implementation and be done with it, make the 500 changes once and once only. If you can’t change the signature then you could use the adapter pattern or wrap the method. If you used an ILoginInfo interface as a parameter, better still, you’ve now go a seam that you can leverage to test any implementation of the interface against that method. All this is even before we talk about code reuse. You could tell in literally seconds the effects of a change on a system. Think DRY. How is that shifting complexity? If anything, it reduces it. It’s this primitive obsession adds needless complexity. What can you do with those primitive types? Add if statements everywhere? Put the logic where it needs to go, which 99% of the time is on the implementation!

1. Follow a standard like JSON API (http://jsonapi.org/) or HAL (http://stateless.co/hal_specification.html).
2. Build a Swagger Specification and generate code libraries using it (http://swagger.io/).
3. Think about building a GraphQL version as well. If you build the controllers correctly you could share much of the same logic between the REST API and GraphQL.

FYI I would love to do a guest blog post about this if you are game showing a simple one in Node.js.

yes – i’ve also been guilty of being the overly “clever” guy and had it bite me and my teams.

p.s, Judging by the end of your reply, I assume you have also came across over engineered solutions in your time with the rationale of the lead engineer trying to be too clever for everyone.

I hear ya… design is all about trade off’s and I agree using a class to encapsulate the parameter will just be shifting the complexity from one area to another. Preaching to the converted.

Sure, it’s always a balance and there is not one prescriptive answer for something being always better. Not changing your method signature for a new parameter can be helpful, but it can also hide new complexity where using your method is easier if that is explicit. If any consumer of your method needs to change because the new parameter is required, you haven’t really gained anything in not changing the signature (you actually have changed the signature, you’ve just hidden the change). Use your head and do what makes sense in a situation and always consider what makes you API most straightforward to understand and abide by the principle of least surprise.

Fair points but is there not also the advantage that if you need more parameters in the future it can be encapsulated and handled in the object.