Une API est le contrat qu’un client utilise pour demander à un système d’effectuer une tâche. Dans le cadre d’un entretien, ce contrat doit rendre les principales actions de l’utilisateur simples et prévisibles : créer une note, la consulter, la modifier, la supprimer et la partager avec une autre personne. Il doit également éviter toute ambiguïté problématique, comme la présence de deux points de terminaison (endpoints) différents qui mettraient « plus ou moins » à jour une même note tout en se comportant différemment face à une même entrée. Illustrons ce contrat à travers une application de notes minimale, où un client mobile ou web communique avec un service backend qui stocke les notes dans une base de données.
Dans cette conception de base, le client envoie une requête HTTP au service API ; ce dernier la valide et applique les règles du contrat, tandis que la base de données stocke les enregistrements des notes afin que les lectures ultérieures reflètent le même état. L’élément clé ici est la capacité d’initiative (ou autonomie) des parties : le client choisit l’appel à effectuer, le service API détermine ce qui est autorisé et ce qui est écrit, et la base de données conserve le résultat pour qu’il soit accessible à la requête suivante. C’est ce modèle que nous privilégierons plus tard, lorsque les capacités d’un serveur unique ne suffiront plus.
L’API fonctionnelle la plus simple nomme clairement les ressources et associe chaque point de terminaison (endpoint) à une action utilisateur unique ainsi qu’à une structure d’objet spécifique. Une note est un objet comprenant un identifiant (id), l’identifiant du propriétaire (ownerUserId), un titre, un corps de texte et des horodatages ; la fonctionnalité de partage introduit une règle permettant à un autre utilisateur de lire ou de modifier la note selon les droits accordés. Ainsi, un nombre restreint de points de terminaison suffit à couvrir le flux principal, sans nécessiter l’invention de verbes supplémentaires ni la surcharge sémantique des méthodes existantes. C’est la correspondance entre chaque point de terminaison et une opération de lecture ou d’écriture qui garantit la lisibilité du contrat, même en cas de forte sollicitation. Voyons comment associer ces points de terminaison aux opérations de lecture et d’écriture du service et de la base de données.