Lors de la création d'une API, dois-je m'en tenir à de petites fonctions et à de nombreux appels, ou à quelques appels et de grandes fonctions?

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 profileet 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 functionsdans 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é.

Que diriez-vous de faire les deux? Avoir une API de " bas niveau " (pour ainsi dire) qui expose les fonctions du système et avoir une autre "couche" qui expose les services qu'un client pourrait vouloir faire. Cette couche utiliserait les API de bas niveau nécessaires, mais celles-ci sont toujours exposées si le client les souhaite.

MISE À JOUR: Pour inclure également certains des grands points et commentaires faits par d'autres.

1. Demandez-vous si le client devra un jour appeler l'une des méthodes API les plus petites, par exemple. Est-il possible d'appeler createUserProfile sans appeler également createUser? Sinon, n'exposez pas cette méthode. Merci NoobsArePeople2

2. Un point simple mais excellent. Point clé avec l'exposition de quelque chose dans une API - vous ne pouvez jamais le défaire. Exposer le minimum nécessaire pour fonctionner puis s'étendre plutôt que de tout exposer et ... eh bien, son nu et ses changements peuvent être embarrassants et maladroits . Merci MichaelT

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:

• Utilisateurs
• Politiques
• Les taux
• ...

Vous devez donc créer des appels d'API autour de ces objets.

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

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.

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.

Personnellement, j'aime les API qui:

1. sont optimisés de manière à ce que les cas d'utilisation courants puissent être facilement exécutés
2. les appels liés aux opérations CRUD sont orientés par lots ou ont des versions par lots
3. permet la réflexion (afin que les personnes qui écrivent des plugins ou des liaisons pour d'autres langages informatiques puissent automatiser le processus)