Should you create your own Interface for all (most/many) Api Calls? (Adapter)

Question

I am currently reading Clean Code by Robert C. Martin and in Chapter 8: Boundaries one can find this paragraph:

We wanted to tell the transmitter something like this:

Key the transmitter on the provided frequency and emit an analog representation of the data coming from this stream

We had no Idea how that would be done [...] we defined our own interface [...] this was the interface we wished we had.

Now I am wondering if one should use this kind of pattern, which appears to be an Adapter, with every Api call I am using. It seems intuitive if I already have the code surrounding the Interface which is how he describes it but if I start out with the data from the API or only do little transformation to the data, it seems to be easier to work with the dataformat, that is given to me.

Or is this a case of me overthinking it and should this (like most things) be used sometimes íf it helps and if so when might this be? In the same situation that he described? Are there more?

Answer 1

Robert Martin's advice is caustic and extreme; perhaps he thinks this is necessary to get the point across. (To those who want to dispute this, he is on record saying that if you make a mistake that costs your employer money,you should writ them a cheque for the amount.)

So when should or shouldn't you create an adapter for using a foreign API? There are basically two reasons why you should do it: code coherence and resilience in the face of change.

Change is the great enemy of comfortable programming. As soon as you've adapted your code base perfectly to the requirements of the environment, the environment will change. A good code base is one that requires only a little work when this happens. Now, if you use a foreign API, the details of using that API will probably change when you want to use cool new features, or upgrade to avoid vulnerabilities, or to achieve parity with your competitor, or many other reasons. If you've created an adapter that encapsulates the foreign code, you'll change the adapter and that's it, no matter how much use you make of the API. If you haven't, then you have to change as many places as there are calls to the API. This is more work --> bad.

But coherence is possibly even more important. Even if you only use that API once and will continue to do so, it is better not to mix concerns e.g. of marshalling arguments, waiting for the result asynchronously, mapping foreign data types etc. with the code that implements your own business logic. This allows you to keep the thinking about this API in one little module and never think about it at all otherwise. And this is an advantage that you get from the first occurrence on.

Answer 2

Having your own interface, has multiple advantages in my eyes.

For one, it helps you to focus on your needs. This makes then the discussion with the other side easier.
Also, you do not have to use the names of the fields, how they are provided in the API. They send a "billingDate" but this is a "invoiceDate" in your app. So you just map it, and then the rest of the application can happily work in "their" language.

But my favorite is, that if the API changes, then you can decide HOW this should be reflected in your application. Eventually you just have to change some mapping, but the internal interface can stay the same. No need to change anything in the deeper core of the application.