One Large API to several microservices vs lots of small APIs each with their own API

Question

I have an application that is beiong split out into a number of services. From a previous question on here, I think that initially JSON/REST is the way to go for communication.

Some of my micro services need to be available publicly, for 3rd parties to use.

So I am now wondering about the best way of structuring this. I can see 2 different structures, each with pro's and cons.

1. Each Service has its own domain and web service layer, so I could have api.customers.mycompany.com, api.documents.mycompany.com, api.users.mycompany.com etc.
2. All the services sit behind a common web service layer, so I have; api.mycompany.com/customers, api.mycompany.com/documents etc...

Option 1 gives a better reduction of dependencies, and maintainability, but at the cost of needing to manage many more domains, and if a 3rd party needs to access several different services, then they need to store and manage several different url's

Option 2 obviously makes maintenance and development harder, as the whole web layer needs to be updated if a new method to any api is added, and the web layer then takes on knowledge of marshalling calls to each specific service. But option 2 also centralises logging, security service error handling and so on. It also means that we (and our 3rd parties) only have a single domain to worry about.

So my question is; for those of you that have gone down this road, which option did you chose, and did you regret it?

Answer 1

Really this is about exposing your microservices individually as opposed to behind a wrapper. I would say that if your services are already 3rd party ready" then simply exposing them would make sense.

However, security and customer friendliness says that you want a single access point that forwards or translates your external API on to the internal service APIs.

I don't think you've given us quite enough info to decide which is "best", but note that if you have a single external API, you can modify your microservices without affecting the API the customer sees. ie if you change one service to use a different API, you can keep the external API unchanged and only modify the calls it makes.

So I'd probably go with option 2, and have it live as a separate project, mostly independent of the microservices. Internally, you bypass this layer completely - its for external access only.