Should I combine or separate APIs for related but distinct entities

apiapi-design

Right now I'm working on a project that's basically a marketplace. The project separates backend (Django + DRF) and frontend where frontend can hit different endpoints based on user interactions with web interface.

The project has two distinct but related entities:

  • buyer;
  • supplier.

So original engineers decided to combine a lot of business logic into common APIs without separating who is interacting with the endpoint – buyer or supplier.
So you hit the API, it calls this or that view and then the view (using service layers) filters out the results based on which group this user belongs to.

On one hand this reduces the number of endpoints, routes and somewhat helps to reduce code duplication.

But on the other hand, when I have to refactor a method I have to mentally trace both entities interacting with this API which introduces a lot of complexity into the code logic.
Not to mention this gives me kind of an imposter syndrome – if the original engineers could figure it out and work with and it's this difficult for me, then I'm not a good engineer

To me code simplicity and "understandability" is more important than DRY – I can deal with code not being DRY by breaking out part of the code into modules or in the worst case by leveraging my RegEx skills together with pretty powerful "Search and Replace" functionality of PyCharm.

So is there a preferable way to design APIs in this regard?
Are there any advantages to combination of API's that I'm not seeing?

Best Answer

On one hand this reduces the number of endpoints, routes and somewhat helps to reduce code duplication.

There's definitely some case to be made against duplication in general, but beware: the issue to address is not how much code is duplicated, but rather how much crafted logic needs to be reinvented.

Having to write two repositories, one for each entity, is not troublesome duplication. Writing role-based authentication twice from scratch, one for each entity, would be troublesome.

But on the other hand, when I have to refactor a method I have to mentally trace both entities interacting with this API which introduces a lot of complexity into the code logic.

This hits the nail on the head.

By default, avoiding complexity tends to win out in terms of what you should strive for. Not that there isn't a lower limit to reasonable complexity, but any codebase of a respectable size will be much more at risk of overcomplication than oversimplification.

The project has two distinct but related entities:

  • buyer
  • supplier

So is there a preferable way to design APIs in this regard?

There is no one-size-fits-all answer to this question.

Context matters. If your application is effectively a marketplace forum where buyers and suppliers are your end users, and 90% of what they do is exactly the same, it makes a lot of sense to have shared logic centered around the User logic. I say User, because the justification for reusability and the fact that you refer to them using a shared name tends to go hand in hand.

However, in other applications the difference between buyers and suppliers may be much larger, to the point where there is little overlap between the two other than some coincidentally similar data fields. That's a very different situation with a very different outcome as far as your question is concerned.

Related Topic