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?

• user44761: I've gone with option 2 (Django with multiple apps). And I'm pretty happy with it. However I fail to see (in my situation at least) how would any "advantage" of option 1 apply. Imho it's quite the opposite - again, it may be true only in my situation. Could you clarify this?
• Ixrec: The question you ask at the very end of this post is generally not accepted on StackExchange, since by definition everyone who reads this will have a different answer, and we focus on questions that can be answered rather than discussed. But the rest of your post is perfectly on-topic and with a bit more detail about your specific use case could easily be an answerable question here, so I'd encourage you to edit it a bit.
• Robert Harvey: 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 -- Well, that's not true. Routing mechanisms make maintaining such url schemes quite straightforward. I would think option 2 would be easier to maintain.
• Kasey Speakman: Are you going to trust that all public clients will correctly coordinate calls between multiple services? I would assume not. So you will have to have a separate API specifically for public consumption.
• Matt: Apologies @lxrec Just going afk now, will edit as soon as I can to make more relevent.

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.