Concevoir une bonne API est un art. Une bonne API est appréciée même après le temps. À mon avis, il ne devrait pas y avoir de parti pris général sur la ligne abstraite-concrète. Certains paramètres peuvent être aussi concrets que des jours de la semaine, d'autres doivent être conçus pour être extensibles (et il est assez stupide de les rendre concrets, par exemple, une partie des noms de fonctions), un autre peut aller encore plus loin et afin d'avoir une élégance L'API dont on a besoin pour fournir des rappels ou même un langage spécifique au domaine aidera à lutter contre la complexité.
Il se passe rarement de nouvelles choses sous la Lune. Jetez un œil à l'art antérieur, en particulier aux normes et formats établis (par exemple, beaucoup de choses peuvent être modélisées après les flux, les descriptions des événements ont été élaborées en ical / vcal). Rendez votre API facilement additive, où les entités fréquentes et omniprésentes sont concrètes et les extensions envisagées sont des dictionnaires. Il existe également des schémas bien établis pour faire face à des situations spécifiques. Par exemple, la gestion des requêtes HTTP (et similaires) peut être modélisée dans l'API avec des objets Request et Response.
Avant de concevoir l'API, réfléchissez sur les aspects, y compris ceux, qui ne seront pas inclus, mais vous devez en être conscient. Des exemples de tels sont la langue, la direction d'écriture, l'encodage, les paramètres régionaux, les informations de fuseau horaire et similaires. Faites attention aux endroits où des multiples peuvent apparaître: utilisez une liste, pas une valeur unique pour eux. Par exemple, si vous concevez une API pour un système de chat vidéo, votre API sera beaucoup plus utile, si vous supposez N participants, pas seulement deux (même si vos spécifications en ce moment sont telles).
Parfois, être abstrait aide à réduire considérablement la complexité: même si vous concevez une calculatrice pour ajouter seulement 3 + 4, 2 + 2 et 7 + 6, il peut être beaucoup plus simple d'implémenter X + Y (avec des limites techniquement réalisables sur X et Y, et ajoutez ADD (X, Y) à votre API au lieu de ADD_3_4 (), ADD_2_2 (), ...
Dans l'ensemble, le choix d'une manière ou d'une autre n'est qu'un détail technique. Votre documentation doit décrire les cas d'utilisation fréquents de manière concrète.
Quoi que vous fassiez du côté de la structure des données, fournissez un champ pour une version d'API.
Pour résumer, l'API doit minimiser la complexité lors de l'utilisation de votre logiciel. Pour apprécier l'API, le niveau de complexité exposé doit être adéquat. Le choix de la forme de l'API dépend beaucoup de la stabilité du domaine problématique. Ainsi, il devrait y avoir une estimation dans quelle direction le logiciel et son API vont croître, car ces informations peuvent affecter l'équation de la complexité. De plus, la conception d'API est là pour que les gens comprennent. S'il existe de bonnes traditions dans le domaine de la technologie logicielle dans laquelle vous vous trouvez, essayez de ne pas trop vous en écarter, car cela facilitera la compréhension. Tenez compte de qui vous écrivez. Les utilisateurs plus avancés apprécieront la généralité et la flexibilité, tandis que ceux qui ont moins d'expérience peuvent être plus à l'aise avec les concrets. Cependant, prenez soin de la majorité des utilisateurs d'API là-bas,
Du côté de la littérature, je peux recommander les programmeurs principaux de "Beautiful Code" expliquent comment ils pensent par Andy Oram, Greg Wilson, car je pense que la beauté consiste à percevoir l'optimalité cachée (et l'adéquation à un usage).