Update: this is an old answer that implies HTTP/1.1. For HTTP/2 the logic is more or less the same except multiplexing, if supported by both ends, allows to have one TCP connection per host.

This is an interesting and important question, I’m surprised it hasn’t gotten much attention.

In addition to @thexacre’s response, you need to consider your client’s behavior and how it may choose to reuse connections. From the client’s perspective a host is a single entity that can serve requests to various paths within one HTTP connection (the Keep-alive feature). The keep-alive timeout can be e.g. one minute but it can be configured on the client side and negotiated with the server. The second factor is the client’s maximum number of simultaneous connections, also configurable but usually limited to save resources.

Having said that, you need to look at how often each of your endpoints will be called by the client and whether the client will benefit from HTTP connection reuse. The one host + multiple paths strategy seems to be more convenient from the client’s perspective, because it may choose to fire multiple requests simultaneously, or to serialize them depending on whether it wants to save local resources (memory and CPU) or to retrieve data as fast as possible.

On the other hand, if a client has to deal with many host names it means it will create separate HTTP connections with each one of them; connection reuse will be impossible.

Then there’s the server side. If you are running a microservice architecture it means for a one-host strategy you will need to have a request router, a potential bottleneck. It is more convenient from the server’s perspective to have separate host names for logically isolated endpoint groups: you will have a flexibility of choosing an architecture (microservice vs. monolithic), changing the architecture later, migration as mentioned in the other answer, potentially no need for a router, etc.

All in all, I would say if the client can potentially make a great number of requests within a limited amount of time, and if it is important to handle them efficiently on the client side then the client will benefit from fewer host names, ideally just one. However, if the client makes only a few requests at a time then consider what’s best for your service, and that would more likely be multiple host names.

Is there a reason to prefer either
dev.taxService.api.company.com or dev.company.com/api/taxService?

It seems basically your question boils down to whether it’s better to use sub-domains or sub-directories to separate services.

It seems there’s plenty of people on either side of the fence, for example:

Google seems to prefer sub-directories, here’s two examples of different services:

• Gmail service: https://www.googleapis.com/upload/gmail/v1/users/userId/drafts
• Analytics service: https://www.googleapis.com/analytics/v3/data/mcf

Amazon seems to prefer sub-domains, for example:

• SQS: http://sqs.eu-west-1.amazonaws.com/
• S3: http://s3-sa-east-1.amazonaws.com/

Personally I generally prefer sub-domains because:

• They don’t require a load balancer / reverse proxy to map the sub-directory to a service.
• Sub-directories make sense in the context of HTTP, but if your service involves other protocols then it may not.
• It’s usually easier to split services between infrastructure providers using sub-domains which is useful during a migration. ie. you can easily move service 1 to provider B by pointing the sub-domain there, while service 2 remains on provider A. Doing that with a sub-directory will probably require you to reverse proxy to a totally separate data centre.

Your question is how should you separate your services: via DNS or via HTTP.

DNS

• Does not require a shared load balancer. Traffic goes directly to that service’s infrastructure.

• No complexity of path/subpath translations.

HTTP

• Clients can re-use connections, improving latency especially for TLS (HTTPS).

• Fewer DNS records and TLS certificates/names to manage.

For me, it’s a matter of how independent the services are.

Is this “one API”? Or “several APIs”?

To me, it sounds like your microservices are all part of the same logical API/application, even if you have implemented them as different processes. So in that particular case, I would separate phases by DNS and microservices by HTTP.