This question is similar to method overloading vs optional parameter but 1) it relates to a service endpoints, and 2) optional parameter may indicate different semantic meaning:
Suppose I provide an endpoint in my service, say "/messaging/subscribe" which basically allows the client to subscribe to some topics. So the subscribe request object may contain a list of topic names and information sufficient enough for the service to send notifications to the subscribing client when a message is published to one of the subscribed topics.
It's also important to note that the service is agnostic to the content of these messages, and that is separately commnuicated between publishers and subscribers. The service just needs to pass some encoding of a published message to all subscribers and they know how to decode it.
Suppose also that clients who wish to subscribe via this endpoint require a SUBSCRIBER role.
Now let's say that I want the service to provide a new, topic monitoring functionality: a client of this new functionality still needs to specify a list of topic names and the means to notify it, but this kind of service:
1) would send meta-data notifications about the topics of interest. These notifications would convey meta-data information about topics such as: "subscriber x has been disconnected from topic y", or "subscriber v subscribed to topic q", or "the number of subscribers on topic z just dropped below 3", or "there have been less than 5 notifications sent to topic w in the last hour"
2) clients of this service require a MONITOR role.
3) Note that the messages in these notifications would be system-defined messages. So their susbcribers could receive a service-defined object representing the message data (e.g. event type, subscriber id, topic name, etc').
There are two ways of handing this:
A new endpoint may be created for the monitoring service, e.g. "/messaging/monitor", with same request object information as the existing subscribe endpoint, and perhaps additional parameters.
Alternatively, the existing endpoint may be overloaded to handle both subscribe and monitor requests, where the difference is conveyed in additional parameters. For example, the client could specify a boolean attribute, named "monitor", in the request object. So if the request does not include this "optional" request attribute or it's value is false, the request is a normal subscibe to the topics. Alternatively if the parameter specifies monitor==true it means the client is only interested in meta-data events related to the specified topics. Role authorization may be checked by the code based on the value of this 'monitor' request attribute.
What are the considerations one should examine in order to decide which of the two alternatives is preferrrable?
Not that it matters, but the implementation uses Vertx in Java...
