Interfaces de programmation (API)

Ce qui suit vise à regrouper diverses réflexions et considérations quant au développement d'une interface de programmation (Application Programming Interface, API), incluant le choix des noms, des signatures de fonctions, les modalités d'appel, la documentation, la gestion des erreurs, etc.

Notez au passage que toutes ces considérations sont traitées individuellement sur d'autres pages de ce site; ce que j'ai essayé de grouper ici tient à l'art (il serait présomptueux de parler d'Art ou de science ici) du design d'outils logiciels qui serviront à des multitudes, et qui constitueront un point d'entrée pour une gamme de services ou de fonctionnalités.

Je dois avouer que le sujet m'intéresse beaucoup, mais que le temps me manque, ce qui explique que vous trouverez ici surtout des réflexions de tiers (un jour, j'ajouterai les miennes). De même, l'organisation par section de cette page est embryonnaire, mais je ferai mieux (éventuellement) quand j'en aurai le temps.

Si vous avez des questions d'ordre plus général sur la pratique de la programmation, voir Pratique-programmation.html

Il y a de plus en plus d'API de type REST. À propos de ces API, voir : ../Web/Developpement-Web.html#api_rest

Généralités

Technique

Qualité

Dans une excellente présentation de 2014 (https://www.youtube.com/watch?v=zgOF4NrQllo pour la présentation, http://meetingcpp.com/tl_files/2013/talks/Keynote-cxx11-library-design-ericniebler.pdf pour les diapositives électroniques), Eric Niebler offre quelques recommandations quant au design d'une API en C++ depuis C++ 11. En résumé :

Pour le design d'une fonction :
- est-elle facile à appeler correctement?
- est-elle difficile àappeler incorrectement?
- peut-on l'appeler efficacement? (Ici, par efficacité, Niebler parle de réduire au minimum les copies, l'aliasing et l'allocation dynamique de ressources)
- est-elle composable avec d'autres fonctions?
- est-elle utilisable dans des constructions de plus haut niveau?

Il met de l'avant un tableau comparatif entre les pratiques recommandées avec C++ 03 et C++ 11 :

Catégorie	Avec C++ 03	Avec C++ 11
Petit intrant	Passage par valeur	Passage par valeur
Sink	s/o	Passage par valeur
Gros intrant	Passage ref-vers-const	Passage ref-vers-const
Petit extrant	Retourner par copie	Retourner par copie
Gros extrant	Passage par référence non-const	Retourner par copie (pertmettre le mouvement et le Copy Elision)
Intrant et extrant	Passage par référence non-const	Passage par référence non-const ou repenser l'interface avec des objets représentant des algorithmes

Comme il le rappelle, dans le cas des intrants, certains sont voués à être utilisés en lecture seule (Read-Only), alors que d'autres sont ce qu'on nomme des Sinks, et sont consommés par la fonction appelée :

pour les paramètres en lecture seule, mieux vaut continuer d'utiliser des paramètres ref-vers-const (sauf s'ils sont très petits, dans quels cas le passage par copie convient)
pour les Sinks, on serait tenté d'utiliser des références sur des rvalue, mais cela pose problème. En effet :
dans une interface avec un paramètre, il faudrait couvrir deux cas :

template <class T>
    void f(const T&); // lecture seule
 template <class T>
    void f(T&&); // Sink

... mais dans une interface avec deux paramètre, il faudrait couvrir quatre cas :

template <class T, class U>
    void f(const T&, const U&); // lecture seule, lecture seule
template <class T, class U>
    void f(const T&, U&&); // lecture seule, Sink
template <class T, class U>
    void f(T&&, const U&); // sink, lecture seule
 template <class T, class U>
    void f(T&&, U&&); // Sink, Sink

... et la situation dégénèrerait par la suite. Pour cette raison, Niebler recommande de consommer les paramètres Sink par valeur
Les paramètres passés comme références sur des rvalue sont pour lui pertinents dans trois cas, soit :
- le constructeur de mouvement
- l'affectation par mouvement, et
- le Perfect Forwarding

Pour ce qui est des objets représentant des algorithmes, Niebler met de l'avant que dans bien des cas, la raison pour laquelle nous avons recours à des paramètres d'entrée/ sortie est que notre algorithme est Stateful, et que cette caractéristique mériterait d'être explicitée par un objet encapsulant ce concept.

Il propose de réécrire getline(), qui « compose mal » avec d'autres fonctions (elle retourne une référence sur le flux duquel la lecture a été faite, pas la ligne lue!) par un getlines() (pluriel) qui encapsulerait les opérations plus primitives de lecture de lignes et réutiliserait l'espace alloué pour la chaîne dans laquelle la première lecture est faite pour que les lectures subséquentes soient plus rapides.

Pour le design des types :

Si votre type implémente le mouvement, visez des opérations de mouvement qui soient noexcept, sinon les conteneurs tels que std::vector ne pourront en déplacer les instances sans risque et devront les copier. Vous perdrez au change
Un objet sur lequel un mouvement a été appliqué, doit se trouver dans un état valide, à tout le moins pour être détruit. L'état d'un objet auquel un mouvement a été appliqué devrait faire partie des invariants de son type
Pour un type supportant le mouvement, il est souhaitable d'avoir un état par défaut qui soit très peu coûteux à atteindre
Privilégiez les types réguliers (ceux qui se comportent comme des int, en gros)
Être un type régulier est différent en C++ 03 et en C++ 11 :
- avec C++ 03, il faut pour l'essentiel s'assurer que le type implémente la Sainte-Trinité et les opérateurs relationnels, qu'on enrichit souvent d'une implémentation spécialisée de swap() pour fins de rapidité d'exécutiona
- avec C++ 11, il faut essentiellement implémenter la règle de cinq (ou de zéro) et les opérateurs relationnels. Étant donné la présence des opérations de mouvement, le std::swap() devient à toutes fins pratiques idéal et il n'est plus pertinent de le spécialiser

Eric Niebler propose le trait suivant pour tester si un type T est régulier :

template <typename T>
   struct is_regular
      : std::integral_constant<
           bool, std::is_default_constructible<T>::value &&
                 std::is_copy_constructible<T>::value &&
                 std::is_move_constructible<T>::value &&
                 std::is_copy_assignable<T>::value &&
                 std::is_move_assignable<T>::value &&
        >
{
};

Ce trait omet les opérateurs ==, != et < qui sont typiquement associés aux types réguliers, alors il est sans doute perfectible.

Pour ce qui est des modules :

Le langage C++ n'a pas, même avec C++ 14, de modules à proprement dit. Cependant, il est possible d'atteindre une forme de contrôle de versions raisonnable avec des espaces nommés inline. Pour cette raison :
- insérez les éléments de l'interface d'un espace nommé dans un espacs nommé inline dès le tout début
- assurez-vous que la version courante de l'interface décrite par l'espace nommé soit inline
Les foncteurs sont mieux pris en charge que les fonctions pour tout ce qui a trait aux règles du Argument-Dependent Lookup.. Ainsi, les foncteurs globaux constexpr sont préférables aux fonctions globales, du moins en général

Saines pratiques

Quelques guides de saines pratiques et quelques groupes de conseils pour vous guider dans le design de vos API :

Pratiques malsaines

Certains ont exprimé leur point de vue par la négative, et nous offrent leur conception de ce qu'il vaut mieux ne pas faire lors du développement d'une API.

Critiques d'API existantes

Les saines pratiques de conception d'une bibliothèque, d'une API ou d'un Framework sont un créneau important des saines pratiques de programmation en général. Plusieurs ont publié leur vision ou leurs expériences à se sujet.