J'ai une plate-forme de rails que je maintiens. Il a beaucoup d'applications Web différentes construites sur lui. Cependant, maintenant, un client demande une API pour qu'il puisse garder les utilisateurs sur son site, mais profiter de certaines des tâches automatisées que nous avons.
La plate-forme est utilisée pour créer des applications d'assurance et permet leur achat en ligne, ainsi que des moyens de télécharger la documentation relative à votre police.
Donc, ma question lors de la construction de l'API est la suivante:
Quand je dois faire beaucoup de choses, comme validate
, créer un user
, user profile
et policy
, à peu près en même temps. Dois-je faire 4 appels API séparés et faire en sorte que le client crée 4 appels de leur côté. OU devrais-je avoir un appel qui exclut beaucoup de paramètres, qui valide le client et crée ces 3 choses en même temps, simplifiant les choses pour le client?
Le client, dans ce cas, obtient toutes les informations requises en même temps, donc ce n'est pas comme s'il y avait un flux naturel dans leur application où il s'arrête et ils peuvent faire un appel API à ma plateforme.
Ayant été du côté client en utilisant de nombreuses API auparavant, mon instinct est de le rendre aussi simple que possible pour le client et de le faire passer un seul appel. Cependant, cela conduit à une taille assez importante functions
dans l'API, dont je ne suis pas fan non plus.
Comment proposez-vous que j'aborde cela?
Je note que je ne suis pas très confiant dans la capacité des clients à implémenter une API compliquée de leur côté.
createUserProfile
sanscreateUser
? Sinon, ne l'exposez pas.Je pense que vous le regardez dans le mauvais sens. Ne vous inquiétez pas pour les grands | petits appels ou beaucoup de | quelques appels.
Pensez aux objets métier et aux actions réalisables avec | pour | contre ces objets.
Tu as:
Vous devez donc créer des appels d'API autour de ces objets.
L'idée est de créer des opérations atomiques ou quasi-atomiques basées sur les objets métier et leurs actions. Cela simplifiera la conception et le codage - des appels qui font ce que doit faire l'objet métier et qui correspond au modèle mental ou aux attentes des programmeurs. Lorsque les programmeurs ou les architectes discutent des exigences avec les analystes commerciaux, ils peuvent tous utiliser la même terminologie et le même flux général d'opérations.
Le problème avec les appels de type tout-en-un plus gros est le risque d'effets secondaires. Si Policy.Create génère également un utilisateur et déclenche une autre action, cela briserait l'attente des programmeurs. De même, de nombreux petits appels forcent le programmeur à se rappeler d'appeler A, puis B puis C pour effectuer une opération commerciale "unique".
Et la façon dont vous nommez les appels sera basée sur ce que Rails et vos services Web de soutien prendront en charge.
Pour être plus normatif, cela créera des appels qui prennent un certain nombre de paramètres et peuvent avoir plusieurs appels sur le back-end qui sont masqués pour le client. Vous vous retrouverez également avec des appels assez rapides / simples où l'API est un peu plus qu'un wrapper pour la routine sous-jacente.
la source
Je pense que votre intuition est bonne - rendez l'API simple pour les consommateurs. Dans une certaine mesure, c'est la philosophie derrière les contrats axés sur le consommateur .
Plus précisément, l'API doit exposer les cas d'utilisation professionnelle appropriés. Tenez compte du domaine d'activité en question - ces fonctions de bas niveau ont-elles vraiment besoin? Quel est l'inconvénient de les encapsuler? Les grandes fonctions de l'API ne sont pas un problème en soi. Ce qui serait un problème, c'est si une grande fonction enchaîne des opérations qui peuvent avoir besoin d'être partitionnées pour permettre l'intervention du consommateur.
la source
Personnellement, j'aime les API qui:
la source