What is the different between /catalog/service and /agent/service/?


Assume I have a local agent run as client mode only (connected to an external server ). Typically, suppose I send /catalog/service/ and /agent/services requests to this local agent. In that case, we will have the same response since the service should be synchronous across all members in the data center.

Please correct me if I have the wrong understanding.


Hi @cheyuxuanll,

Consul is designed for services to be registered against a Consul client agent which is running on the same host where a service is deployed. The /v1/agent/service/ endpoints provide a way for you to interact with services which are registered with the specific Consul agent to which you are communicating, and register new services against that agent.

Each Consul agent in the data center submits its registered service information to the Consul servers. The servers aggregate this information to form the service catalog (https://www.consul.io/docs/architecture/anti-entropy#catalog). The /v1/catalog/ endpoints return that aggregated information.

The /catalog/service/ endpoint will contain information that has been successfully submitted by the agents to the servers. If a particular agent is unable to communicate to the servers, it is possible for a service instance to be visible in /agent/service/:id on that agent, but not visible in the output of /catalog/service/:name (edit: this should be service name, not ID) for the rest of the cluster.

See this related answer I provided to a user on StackOverflow for a bit more info https://stackoverflow.com/a/65725360/12384224.

Let me know if you have any other questions.

Hi @blake ,

Thanks for your reply.

So, if everything is ok:

/agent/service would return all services: services in that local agent

/catalog/service/ would return all services: services that successfully register to the service catalog.


In client agent one, if I want to access the service in this agent, I need to use /agent/service/:id. If I want to access the service in other agents ( service agents or other client agents), I need to use /catalog/service/:id

Please correct me if I was wrong.

@cheyuxuanll, yes, your understanding is correct. :slight_smile:

In addition to the /catalog/service/:service_name endpoint (correction from previous post, this is name not ID) , you can also use /health/service/:service_name if you need to retrieve health check information for the registered services.

https://learn.hashicorp.com/tutorials/consul/get-started-service-discovery#http-api shows an example of using this API to return only services with health checks in the passing state.

@blake Thanks!

So, is it preferable to deploy the service and register service (to the local agent) in the same host?

Yes. That is the recommended deployment model.

1 Like