Jusqu’à présent, nous avons uniquement vu des endpoints basiques pour obtenir une liste de ressources ou une ressource unique par ID. Mais il existe tellement plus de possibilités avec les API ! 💪 Selon la manière dont vous concevez vos URI, vous pouvez créer des requêtes plus complexes comme la recherche, le classement, et plus encore. Nous reprendrons l’application InstaPhoto 📸 pour décider de quels types d’URI complexes vous aurez besoin.
Filtrez
Et si vous vouliez que vos utilisateurs puissent rechercher des photos pour des lieux particuliers ? Faites entrer les filtres ! Vous pourriez concevoir un endpoint comme celui-ci :
GET /photos?location={locationId}Ce ”?” est nouveau ! Le point d’interrogation est un moyen pour l’API de savoir que vous passez un paramètre. Un paramètre est une donnée qui sera manipulée, utilisée d’une certaine manière par le client, le serveur ou le programme informatique visé : ici, l’API. Il vous permet de créer une requête qui peut changer selon le terme recherché. Dans ce cas, vous voulez que les utilisateurs puissent rechercher une location (ou un lieu) égale à = locationId. Ainsi, vous pouvez écrire tout ID de lieu dans le paramètre de requête, et vous pourrez voir des photos de ce lieu. 🙏🌍
Attends – je pensais que ces valeurs étaient uniquement appelées endpoints quand elles contenaient le nom de domaine et l’URI !
C’est une bonne remarque. Oui, les URI sont le chemin de la ressource, et un endpoint correspond au nom de domaine plus le chemin de la ressource.
Recherchez
La recherche vous permet de faire une requête sur une liste de ressources correspondant à votre requête de recherche. OK, alors admettons que vous vouliez avoir un endpoint où les utilisateurs peuvent rechercher toutes les photos qui ont un quelconque rapport avec le snowboard 🏂. Votre endpoint pourrait être celui-ci :
GET /photos?search=snowboard
Si vous avez déjà utilisé la fonctionnalité de recherche sur Twitter, vous avez pu constater que leur API de recherche fonctionne de façon très similaire !
Quelle est la différence entre le filtrage et la recherche, alors ? 🤔
C’est une question courante, qui dépend de la façon dont on trouve un élément. Pour filtrer, vous partez d’un élément plus petit et plus spécifique et vous collectez tous les items qui correspondent à cette valeur. Par exemple : vous allez chercher toutes les séries comiques qui commencent par la lettre C. Dans ce cas, vous filtrez.
La recherche constitue une approche plus large et élargit votre périmètre à toute chose associée à une certaine valeur.
Triez
Disons que vous voulez que vos utilisateurs voient tous leurs followers par ordre alphabétique ascendant et par nom de famille. Ce qui est assez complexe. Vous pouvez créer un endpoint pour cela !
GET /users/{userId}/followers?sort=lastName&order=ascLe & est nouveau ici ! Il vous permet d’enchaîner différentes requêtes ensemble ! Par exemple, vous pouvez trier les utilisateurs par lastName (nom de famille) en ordre ascendant. Vous avez déjà vu un résultat trié quand vous naviguez sur le web. Mais si ! D’habitude, vous voulez voir les publications les plus récentes sur Twitter ou Instagram – ce qui constitue en fait un tri par date !
Vous pouvez enchaîner tous types de requêtes différentes entre elles. Par exemple, si vous voulez voir tous les utilisateurs vérifiés avec le prénom (firstName) Jamie, vous pouvez faire la requête suivante :
GET /users?verified=true&firstName=Jamie
Si vous voulez voir toutes les photos prises à New York qui ont été postées le soir du 31 décembre et qui ont plus de 5 000 likes, vous pouvez faire la requête suivante :
GET /photos?location=NYC&created_at=2018-12-31&likes_greater_than=5000
Et vous pouvez encore en ajouter ! ✨
Pour que ces options fonctionnent, il vous faudra installer cette fonctionnalité en utilisant le langage de code que vous avez choisi pour l’application, car aucun d’entre eux n’est intégré à une API lorsque vous la créez. Ici, nous avons juste simplement illustré quelques-uns des moyens possibles dont vous pouvez utiliser les requêtes avancées dans votre API.
Paginez vos résultats
InstaPhoto 📸 a décollé et rencontre un immense succès ! 🙏 Mais vous avez maintenant des milliers de photos dans votre base de données, ce qui a rendu vos endpoints /photos très lents, au grand dam de vos utilisateurs. 😰 Que faire ? Le moyen pour corriger cela se trouve dans ce qu’on appelle la pagination. Cela signifie que vos endpoints ne retournent qu’un nombre limité d’entrées par numéro de page dans votre réponse. Vous pouvez décider de combien d’items vous voulez sur chaque page, mais habituellement ce chiffre se situe entre 10 et 100.
Pour faire plus simple, /photos renvoie toutes les photos de votre application. Au lieu d’avoir /photos, vous devez donc préciser la page que vous voulez obtenir dans la requête :
GET /photos?page=23
Ainsi, vous obtiendrez uniquement la 23e page de photos qui en contient, disons 100 par exemple, et non la totalité d’entre elles. Le temps de chargement sera réduit et votre utilisateur sera ravi ! Pour voir les photos suivantes, on peut imaginer que votre utilisateur clique sur un bouton pour charger la suite. Et vous aurez donc :
GET /photos?page=24
Et ainsi de suite ! ✨
De la même façon, lorsque vous effectuez une recherche Google, il n’est pas rare d’obtenir des millions de résultats ; du coup, Google ne renvoie qu’une page des résultats les plus haut classés, et vous pouvez parcourir le reste pour en voir plus.
Google a besoin de paginer ses résultats pour ne pas surcharger votre UI.
La pagination permet aux utilisateurs de votre API de n’appeler qu’une page de résultats à la fois, pour que votre client ou votre UI ne soit pas débordé par les résultats !
Versionnez
Le dernier outil de design important pour les API est le versioning (ou versionnage). En donnant une version à vos API, vous pourrez facilement suivre les changements et vous assurer que votre application puisse être compatible pour les versions antérieures. Cela signifie que vous pouvez continuer à mettre à jour votre API, tout en garantissant que les utilisateurs dépendants d’une version plus ancienne puissent continuer à l’utiliser. Par exemple, si certains de vos clients utilisent déjà la version 1 de votre API, vous pouvez publier une version 2 de votre API. Alors, les utilisateurs de la version 1 de l’API peuvent continuer à l’utiliser jusqu’à ce qu’ils soient prêts à passer à la version 2. Les développeurs peuvent versionner leurs API de deux manières :
Ajoutez un champ version dans vos paramètres d’en-tête de requête : "accept-version": "1.3".
Ajoutez une version à votre URI : /v1/.
L’approche la plus courante est d’ajouter un /v1 au début de votre URI :
GET /v1/photos
Les éléments ci-dessus sont des fonctionnalités basées sur le design et que vous devez prendre en compte pour le contenu de votre API, puisque vous devrez choisir votre propre langage ou framework. Nous aborderons ce sujet dans le dernier chapitre.
En résumé
Le filtrage, la recherche et le tri sont des moyens d’ajouter de la complexité à vos requêtes API.
La pagination aide vos clients et utilisateurs API à éviter d’être submergés par trop de données.
Le versionnage vous permet de continuer à mettre à jour votre API sans casser le code des personnes qui en dépendent déjà.
Vous venez de faire un sacré bout de chemin : vous avez construit votre première API et découvert les fonctionnalités avancées des endpoints. Mais qu’en est-il si vous souhaitez coder votre propre API ? Quels frameworks existent ? Quels langages utiliser ? Abordons cela rapidement dans le prochain et dernier chapitre de ce cours. 🎉
