Várias APIs ou uma API com um parâmetro "seletor"?

Digamos que você tenha um serviço da Web, que adiciona lógica de negócios a uma fonte de dados. A aparência de cada API desse serviço é: dado um conjunto de restrições, forneça os itens da fonte de dados que satisfazem essas restrições. Você pode dizer que obtém uma "visualização" da fonte de dados de volta da API.

Agora, com o tempo, você é solicitado a retornar diferentes tipos de visualizações sobre a fonte de dados. Você tem a opção de adicionar novas APIs para cada exibição "suficientemente distinta" ou alternar de marcha e fornecer uma API getFooDataView (), que aceita um parâmetro que especifica o tipo de exibição que você deseja. Você tem várias pressões concorrentes para decidir qual caminho seguir:

• O grande cliente existente do seu serviço prefere ser preguiçoso e não precisa codificar até novas APIs quando novas visualizações dos dados são necessárias.
• Porém, alguns de seus parâmetros de solicitação (restrições) só fazem sentido para algumas visualizações, e não para outras - você teria que tornar o contrato da API mais flexível dizendo "bem, se você deseja a visualização XYZ, definir o parâmetro" foo "terá sem efeito ", com o efeito colateral lamentável de que você não pode tornar" foo "um parâmetro necessário, mesmo que seja o caso em algumas das visualizações.
• Está se tornando cada vez mais o caso de novos clientes que desejam alavancar seu serviço. Você não pode decidir o que seria mais confuso para eles - tendo que escolher entre APIs diferentes, porém mais definidas, e uma API em que eles precisam saber qual combinação de parâmetros realmente lhes dá o que desejam.

Para destilar isso, quando você define que algo deve ser sua própria API, em oposição a uma variação de uma API existente? Pessoas diferentes com quem você trabalha têm visões diferentes sobre o que torna duas solicitações de clientes semanticamente distintas, portanto, pode ser difícil gerar consenso sobre esse assunto. Você também deseja garantir que seu serviço não seja proibitivamente difícil para futuros clientes consumirem. Quais são algumas das práticas recomendadas para fazer esse tipo de escolha?

Pessoalmente, eu me inclinaria para APIs menores e mais apertadas. Eu não acho que isso aconteça que ter uma API de tamanho único torne algo mais simples de usar - na verdade talvez seja o inverso, já que você precisa descobrir a combinação certa de "ju-ju" de tipo fraco para obter o que você deseja, enquanto uma API mais rígida pode se tornar mais auto-explicativa. Você está apenas ocultando a complexidade em vez de torná-la explícita.

Também é provável que sua API única se torne cada vez mais complexa à medida que envolve mais e mais funcionalidades, enquanto as APIs mais rígidas permanecem focadas e enxutas.

Isso cheira ao Princípio de Segregação de Interface em uma escala maior.

Sempre existem outras maneiras (como uma boa orientação) para ajudar os clientes a escolher a abordagem certa.