Concevoir une API

Passer du cahier des charges à une API

Comme la plupart des technologies, une API est une solution à un problème. Afin de concevoir l'API adaptée, vous devez clairement définir le problème à résoudre en répondant aux questions suivantes :

• Qui sont les consommateurs cible de cette API ?
• Quel genre d'informations les consommateurs vont-ils manipuler avec cette API ?
• Quelles actions les consommateurs vont-ils effectuer sur l'API ?

Par exemple, si vous êtes une entreprise de livraison de repas, vous pouvez construire une API permettant à votre partenaire réseau de parcourir et rechercher dans une base de données de restaurants ceux fournissant un service de livraison.

Dans cet exemple, votre API cible plusieurs partenaires de votre entreprise. Votre partenaire devra manipuler des données relatives aux restaurants et effectuer des requêtes de recherche sur les données, avec des options de filtre et de tri.

Un autre exemple : si vous travaillez dans une entreprise éditant des calendriers logiciels, vous pouvez vouloir construire une API afin que les développeurs front-end dans le monde puissent créer de nouvelles applications mobiles et Web en se basant sur votre système de calendrier.

Penser aux consommateurs de votre API est la première étape pour leur assurer une bonne expérience de développement. Cela permettra à votre API de se démarquer et d'augmenter son niveau d'engagement.

Les éléments constitutifs d'une API

Quatre concepts entrent en jeu lors de la définition d'une API :

• Une ressource Resource est un élément avec lequel les consommateurs interagissent dans l'API. Les ressources sont identifiées de manière unique par un chemin, qui, combiné à l'endpoint de l'API fournit une adresse unique pour une ressource sur le Web. Par exemple, Calendars est le nom d'une ressource correspondant à une liste de calendriers et son chemin est /calendars.
• Une Operation est l'action qui peut être effectuée sur vos ressources. Les opérations les plus courantes sont GET (lecture), POST (création), PUT (mise à jour), DELETE (suppression). Par exemple, List all Calendars est le nom de l'opération utilisant la méthode GET sur la ressource Calendars.
• Un type de données (Data type) est une description des données réelles échangées sur le réseau. Par exemple, Calendar est le nom d'un type de données qui décrira toutes les propriétés d'un calendrier Calendar, comme son nom, son propriétaire et une référence aux événements qui appartiennent à ce calendrier. L'opération List all Calendars retourne une liste de types de données Calendar.
• Un composant (Component) est un élément pouvant être réutilisé dans toute la définition de l'API. Par exemple, si vous devez utiliser le même paramètre de requête dans plusieurs opérations, vous pouvez le créer en tant que composant et y référer dans autant d'opérations que vous le souhaitez.

D'autres éléments utiles constituent une API :

• Un Endpoint est le point d'entrée principal de votre API sur le Web. Un endpoint se compose d'un schéma, comme HTTPS et d'un hôte comme www.calendar-api.com.
• Un bloc de texte Text peut être utilisé pour saisir du texte (y compris en Markdown) et le placer n'importe où dans votre définition d'API. Utilisez des blocs de texte pour expliquer des éléments transverses comme l'authentification et la gestion d'erreurs.
• Une Section est utilisée pour regrouper de manière significative des ressources et des types de données. Utilisez-les pour rendre votre définition d'API plus claire et plus simple à utiliser pour les développeurs. Vous pouvez glissez-déposer des éléments dans des sections dans le panneau de gauche. Vous pouvez également réorganiser les sections entre elles.

Dans Talend Cloud API Designer, vous pourrez créer ces éléments depuis le menu + dans le panneau de gauche.

Les endpoints sont créés dans l'écran des informations générales, auquel vous pouvez accéder en cliquant sur le nom de votre API, en haut du panneau de gauche. Un endpoint peut avoir le statut Published (Publié) ou Not published (Non publié). S'il est publié, il s'affiche dans la documentation en temps réel et dans API Portal.