Ao criar uma API, devo ficar com pequenas funções e muitas chamadas, ou algumas chamadas e funções grandes?

Eu tenho uma plataforma de trilhos que mantenho. Ele tem muitos aplicativos Web diferentes criados sobre ele. No entanto, agora um cliente está solicitando uma API para que ele possa manter os usuários em seu site, mas aproveite algumas das tarefas automatizadas que temos.

A plataforma é usada para criar aplicativos de seguro e permite a compra on-line, além de fornecer maneiras de baixar a documentação relacionada à sua política.

Então, minha pergunta ao criar a API é esta:

Quando eu tenho que fazer um monte de coisas, como validate, criar um user, user profilee policy, praticamente ao mesmo tempo. Devo fazer 4 chamadas de API separadas e fazer com que o cliente crie 4 chamadas do lado deles. OU devo ter uma chamada que excede muitos parâmetros, que valida o cliente e cria todas essas três coisas ao mesmo tempo, simplificando as coisas para o cliente?

O cliente, nesse caso, obtém todas as informações necessárias ao mesmo tempo, portanto, não é como se houvesse um fluxo natural no aplicativo em que ele faz uma pausa e eles podem fazer uma chamada de API para minha plataforma.

Tendo estado no lado do cliente usando muitas APIs antes, meu intuito é facilitar o máximo possível para o cliente e fazer com que eles façam apenas uma chamada. No entanto, isso está levando a um grande número functionsna API, da qual também não sou fã.

Como você sugere que eu resolva isso?

Como observação, não estou muito confiante na capacidade dos clientes de implementar uma API complicada do lado deles.

Que tal fazer as duas coisas? Tenha uma API de " baixo nível " (por assim dizer) que exponha as funções do sistema e outra "camada" que exponha os serviços que um cliente pode querer fazer. Essa camada usaria as APIs de baixo nível necessárias, mas elas ainda serão expostas se o cliente as desejar.

ATUALIZAÇÃO: Para incluir também alguns dos grandes pontos e comentários feitos por outros.

1. Considere se o cliente precisará chamar um dos métodos de API menores, por exemplo, é possível chamar createUserProfile sem também chamar createUser? Caso contrário, não exponha esse método. Obrigado NoobsArePeople2

2. Um ponto simples, mas excelente. Ponto-chave da exposição de algo em uma API - você nunca pode expor isso. Exponha o mínimo necessário para funcionar e depois expanda em vez de expor tudo e ... bem, então suas mudanças nuas e fazendo mudanças podem ser embaraçosas e embaraçosas . Obrigado MichaelT

Eu acho que você está olhando de maneira errada. Não se preocupe com grandes | pequenas chamadas ou muitas | algumas chamadas.

Pense nos objetos de negócios e nas ações que podem ser executadas com | para | contra esses objetos.

Você tem:

• Comercial
• Políticas
• Tarifas
• ...

Portanto, você deve criar chamadas de API em torno desses objetos.

• User.Create
• User.UpdatePassword
• Policy.Validate
• ...

A idéia é criar operações atômicas ou quase atômicas com base nos objetos de negócios e em suas ações. Isso simplificará o design e a codificação - chamadas que fazem o que o objeto de negócios deve fazer, que corresponde ao modelo mental ou às expectativas dos programadores. Quando os programadores ou arquitetos estão discutindo os requisitos com os analistas de negócios, todos podem usar a mesma terminologia e fluxo geral de operações.

O problema com chamadas maiores, do tipo multifuncional, é o risco de efeitos colaterais. Se o Policy.Create também gerar um usuário e acionar alguma outra ação, isso quebraria a expectativa dos programadores. Da mesma forma, muitas chamadas pequenas forçam o programador a lembrar de ligar para A e B e C para executar uma operação comercial "única".

E como você nomeará as chamadas será baseado no que o Rails e seus serviços web de suporte suportarão.

Para ser mais prescritivo, isso criará algumas chamadas que usam vários parâmetros e podem ter várias chamadas no back-end que são obscurecidas para o cliente. Você também terminará com algumas chamadas bastante rápidas / simples, nas quais a API é pouco mais que um invólucro para a rotina subjacente.

Acho que seu pressentimento está certo - simplifique a API para os consumidores. Até certo ponto, essa é a filosofia por trás dos contratos orientados ao consumidor .

Mais especificamente, a API deve expor casos de uso de negócios adequados. Considere o domínio comercial em questão - há realmente uma necessidade dessas funções de baixo nível? Qual é a desvantagem de encapsulá-los? Grandes funções na API não são um problema por si só. O que seria um problema é se uma grande função sequenciar operações que talvez precisem ser particionadas para permitir a intervenção do consumidor.

Pessoalmente, gosto de APIs que:

1. são otimizados de maneira que casos de uso comuns possam ser facilmente executados
2. chamadas relacionadas a operações CRUD são orientadas por lote ou têm versões em lote
3. permite reflexão (para que as pessoas que escrevem plugins ou ligações para outras linguagens de computador possam automatizar o processo)