As part of my work, not a litte part of it, is the APIs. What we want to reveal? the way we going to do so, the encapsulation and all other things that will describe the functionality we give.
But, more than once I found out that the bad experience is not by the way the API is written but by what it revealing. I’m taking about “The road to hell is paved with good intentions”.
For example you have a developer that got a mission to create an API for “Account Management”;
- Create account
- Find account by name
- Delete account by Id
Now’ your developer knows that it’s important to reveal the next methods that not written in the S.R.S. like;
- Clone account
- Find account by surname
- Delete account by name
Yes, I also believe that the functionality above is necessary and needed to be include. But from add this functionality and reveal it on the API are two different things.
Separate the Interfaces
Actually we have two interfaces with shared functionality, but still two.
If the first one IAccount is to ensure the functionality we required from the Account class to support.
The second one IAccountApi is to ensure the functionality we required from the API to support. Yes most of the time IAccount will include totally the IAccountApi interface, or even be identical, but still are two different responsibility areas.
Why is that? Enabling Factors!!!
One of the principles that must be followed to ensure proper modularity is:
Small interfaces (coupling) :
Two communicant modules should exchange as little information as possible. and this is to ensure
- Continuity: the ability of the system to changes
- Protection: the ability of the system to robustness
One of the must dangers things in Software are dead hidden code, that all know that are not in use and that it’s not good no more, all but one and that one developer one day start to use it and cause a lot of problems on your system. Now go and tell him that you not support it for few months / years. Still it’s to late!!!
Remember that by using small and accurate interfaces, the possibility to impact the other components that use is small. Less errors and less problems on code change.
So, keep the interface small and accurate as you can before someone will activate it ☺