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.
createUserProfilesem tambémcreateUser? Caso contrário, não o exponha.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:
Portanto, você deve criar chamadas de API em torno desses objetos.
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.
fonte
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.
fonte
Pessoalmente, gosto de APIs que:
fonte