Concevez les endpoints de votre API

Lors de la création d’une API, il est important de ne pas se lancer tête baissée et de réfléchir à l’architecture de votre API, quitte à tout poser sur papier avant. Quel sera le rôle de votre API ? Quelles seront les ressources ? Quels seront les différents accès autorisés pour les utilisateurs ?

Bien structurer votre API dès le début de sa conception vous permettra d’anticiper les erreurs mais aussi d’avoir une API plus solide et mieux conçue.

Dans ce chapitre, vous ne coderez pas une API mais allez la concevoir. C’est un exercice de réflexion, afin de vous préparer au mieux à la création d’une API.

Concevez une API de partage de photos

Dans cette partie, nous allons réfléchir à la manière de concevoir une API pour une application de partage de photos nommée InstaPhoto. 📸  Nous voulons que les utilisateurs puissent publier et partager des photos avec leurs amis, commenter les photos des autres, créer des hashtags, rechercher des photos par localisation, la totale, le grand jeu !

Prenez une minute pour écrire ce à quoi vous avez besoin de réfléchir lors de la conception d’une API pour InstaPhoto. De quelles ressources avez-vous besoin ? Quels URI seraient compréhensibles par d’autres développeurs ? C’est aussi une belle occasion de revoir ce que vous avez appris dans les parties précédentes  !

Voici quelques exemples de ressources dont vous aurez absolument besoin :

• Photo ;

• User ;

• Location (localisation, en français) ;

• Post.

À partir de là, vous pouvez commencer à réfléchir à des questions importantes, comme celles-ci :

• Quels endpoints auront besoin d’autorisations ?

• Quelles ressources voulez-vous pouvoir mettre à jour ?

• Aurez-vous besoin de pouvoir modifier des publications après leur création ?

• Les commentaires doivent-ils pouvoir être supprimés ? 

• Avez-vous besoin de toutes les opérations CRUD pour chaque ressource ? Ou seulement d’une ou deux ? Lesquelles ?

Il n’y a pas de bonne ou de mauvaise réponse ici – cela dépend simplement de l’application InstaPhoto que vous voulez développer ! À vous de choisir ! ✨

Créez vos endpoints

Lors de la conception d’endpoints, le naming (ou nommage, en français) est un élément clé. Vous voulez que les développeurs qui l’utilisent comprennent naturellement ce que chaque endpoint est censé faire. Les conventions de naming actuelles demandent d’inclure uniquement la ressource que vous voulez mettre à jour, et non le verbe que vous voulez mettre en œuvre. 

Pour faire simple, utilisez uniquement le nom de la ressource dans l’URI, car l’action se trouve déjà dans le verbe HTTP. Cela donnerait : 

• POST /photo

• PUT /photo

• GET /photo

Puisque que le verbe de l’action est déjà inclus dans la requête HTTP, il n’est pas nécessaire de le préciser lors de la conception des endpoints.

Pour que vous puissiez mieux comprendre, des endpoints mal nommés ressembleraient à ceci :

• POST /createPhoto

• PUT /updatePhoto

• GET /getPhoto

Simulez des endpoints supplémentaires

Considérons les endpoints possibles pour notre InstaPhoto.

Ici aussi, il n’y a pas de bonne ou de mauvaise réponse, cela dépend simplement des besoins de votre application et de la façon dont vous voulez la concevoir.

Imaginons que vous vouliez que les utilisateurs soient en capacité de créer, voir et supprimer des photos – mais pas de les modifier une fois publiées. Tous ces éléments nécessitent également une authentification, car vous ne voudriez pas que les utilisateurs puissent publier, modifier ou supprimer des photos qui ne leur appartiennent pas ! 🔐

Maintenant, prenez une feuille de papier et écrivez quelques endpoints pour créer, voir et supprimer des photos. Rappelez-vous que vous voudrez peut-être spécifier une photo en particulier à visionner et à mettre à jour, non ? 😉 Une fois que vous aurez fini, regardez juste en-dessous si ce que vous avez écrit correspond à mes réponses.

Vu que l’on veut généralement voir ou supprimer des photos en particulier, le fait d’ajouter un ID pour les deux derniers endpoints est logique. Il permet à l’API de savoir de quelle photo il s’agit.

Et maintenant, vos utilisateurs ! De quels verbes HTTP aurez-vous besoin pour un compte utilisateur ? 🤔 Et puis, même si vous ne voulez pas que les utilisateurs puissent modifier leurs photos une fois qu’elles sont déjà créées, il doivent au moins pouvoir modifier leur profil utilisateur ! Par ailleurs, vous voulez qu’ils puissent voir les informations disponibles publiquement sur un utilisateur sans authentification (exactement comme l’API GitHub) ; donc pour cet endpoint, vous n’aurez pas besoin d’authentification. Quelles sortes d’endpoint pourriez-vous concevoir pour cela ?

Et maintenant, les commentaires  ! Comment les ajouter ? Si vous voulez que les utilisateurs puissent commenter les photos d’un autre utilisateur, il vous faudra imbriquer une ressource dans une autre. Et ce, parce qu’un commentaire doit être associé à une photo spécifique. Par exemple, imaginons que vous vouliez créer un nouveau commentaire pour une photo avec ID. Vous pourriez créer l’endpoint POST /photos/{photoId}/comments. Utilisez POST parce que vous créez quelque chose. Ensuite, travaillez en arrière : créez un commentaire (/comments) pour une photo spécifique (/{photoId}) parmi toutes les autres photos (/photos).

Et maintenant, voici une description de trois endpoints supplémentaires que vous devrez créer :

• obtenir tous les commentaires pour une photo spécifique avec l’ID {photoId} ;

• obtenir le commentaire avec l’ID {commentId} pour la photo avec l’ID {photoId} ;

• supprimer le commentaire avec l’ID {commentId} pour la photo avec l’ID {photoId}.

Vous ne voulez pas que les commentaires soient modifiables, n’incluez donc pas d’endpoint pour cela. Essayez d’écrire les endpoints pour ces trois éléments.

Tous ces endpoints nécessitent une authentification, car ils doivent seulement être modifiables par l’utilisateur qui les a créés, et non les autres. Et vous pourriez adopter le même mode de raisonnement pour toutes les autres ressources dont vous aurez besoin.

En résumé

• Lors de la planification, pensez à quelles opérations CRUD seront nécessaires aux ressources.

• Utilisez des noms de ressources et non des verbes en nommant les endpoints.

• Pensez aux ressources que vous devrez imbriquer dans d’autres ressources.

• Pensez aux ressources qui nécessiteront une authentification.

Vous avez la liste des opérations CRUD nécessaires, vos ressources et leur nom, les ressources complémentaires, celles qui nécessiteront une authentification, la liste de vos endpoints. Votre base est solide, mais vous pouvez approfondir le tout avec la recherche, par exemple. Passez au chapitre suivant, nous allons étoffer nos endpoints grâce à quelques fonctionnalités avancées !