Conception d'API

Passer des exigences à une API

Comme la plupart des technologies, une API est une solution à un problème. Pour concevoir la bonne API, vous devez vous assurer que le problème que vous abordez est clairement défini en répondant aux questions suivantes :

• Qui sont les consommateurs cibles de cette API ?
• Quel type d'informations les consommateurs manipuleront-ils via l'API ?
• Quelles actions les consommateurs effectueront-ils sur l'API ?

Par exemple, si vous êtes une entreprise de livraison de produits alimentaires, vous pourriez vouloir créer une API pour votre réseau de partenaires qui leur permettra de parcourir une base de données de restaurants auxquels vous fournissez un service de livraison et d'y effectuer des recherches.

Dans cet exemple, votre API cible les 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.

Autre exemple : si vous êtes une entreprise SaaS de calendrier, vous pourriez vouloir créer une API afin que d'autres développeurs front-end dans le monde puissent générer de nouvelles applications mobiles et Web basées sur votre système de calendrier.

La détermination des consommateurs de votre API constitue la première étape pour leur offrir une bonne expérience de développement. Cela aidera votre API à se démarquer et à augmenter les niveaux d'engagement.

Les éléments qui composent une API

Il existe quatre concepts clés utilisés lors de la conception d'une API :

• Une Ressource est un élément avec lequel vos consommateur·trices interagissent via votre 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 qui correspond à une liste de calendriers et son chemin d'accès est /calendars.
• Une Opération est l'action qui peut être effectuée sur vos ressources. Les opérations les plus courantes sont GET (read), POST (create), PUT (update) et DELETE. Par exemple, List all Calendars est le nom d'une opération qui utilise la méthode GET sur la ressource Calendars.
• Un Type de données 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 Calendar (Calendrier), comme son nom, son propriétaire et une référence aux événements qui lui appartiennent. L'opération List all Calendars renvoie une liste de types de données Calendar.
• Un Composant est un élément pouvant être réutilisé tout au long de 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 faire référence dans autant d'opérations que nécessaire.

Voici d'autres éléments utiles qui composent 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 tel que HTTPS et d'un hôte tel que www.calendar-api.com.
• Un bloc de Texte peut être utilisé pour saisir librement un texte (y compris un markdown) et le placer n'importe où dans votre conception d'API. Utilisez des blocs de texte pour expliquer des sujets transversaux comme l'authentification et le traitement des erreurs.
• Une Section est utilisée pour grouper des ressources et des types de données de manière significative. Utilisez-les pour rendre la conception de votre API plus claire et plus intuitive 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 API Designer, vous pourrez créer ces éléments depuis le menu Create new (Créer) dans le coin supérieur droit.

Les URL de serveur sont créées dans l'écran d'informations générales. Une URL de serveur peut être Published (Publiée) ou Not published (Non publiée). Si elle est publiée, elle s'affiche dans la documentation en temps réel.