5. Les ressources

Par rapport à notre exemple précédent, nous allons avoir besoin de récupérer certaines données pour afficher un pokémon à l’utilisateur. Et vous vous en doutiez, c’est notre API Rest qui va nous fournir ces données. C’est même son rôle principal.

En fait, une API Rest est structurée autour de la notion de ressources. Son boulot, c’est d’exposer ou non certaines ressources du serveur au monde extérieur. Une fois ces ressources exposées, tous les services autorisés peuvent venir récupérer et utiliser ces ressources : une application web, une application mobile, et même une autre application web.

Une ressource peut-être n’importe quelle donnée que vous souhaitez rendre disponibles aux utilisateurs de votre API Rest. Si vous avez une application de météo, alors vos ressources seront les différentes températures disponibles. Si vous avez une application de réseau social, alors les ressources pourront être les utilisateurs inscrits sur la plateforme, ou encore les publications de tel et tel utilisateur. Dans notre cas, il s’agit d’une application de pokémons, donc les ressources sont … des pokémons !

Le problème, c’est comment rendre accessible ces ressources depuis notre API Rest, non ? 🤔

Exactement. Et c’est maintenant que la magie va opérer.  🔥

Les ressources ont des adresses, qui nous permettent de les retrouver. Et ces adresses sont … des urls !

Et oui, car url signifie « Uniform Ressource Locator« , c’est-à-dire l’adresse de vos ressources. Donc chacune de vos ressources aura une adresse associée.

Donc, la liste de tous nos pokémons sera accessible à l’adresse :

my-web-app.com/my-api-rest/pokemons // version pédagogique.
pokedex.com/api/pokemons // version plus "réaliste", qui pourrait exister.

On remarque que nos ressources sont accessible depuis une adresse ressemblant à ceci :

URL de votre site + préfixe de votre API Rest + Ressources

L’url de votre site, c’est l’adresse à laquelle se trouve votre site sur le web. Généralement, en rentrant l’url de votre site dans la barre de recherche d’un navigateur, vous devriez tomber sur la page d’accueil.

Ensuite, on utilise un préfixe pour notre API Rest, afin de distinguer les pages d’un site par rapport aux ressources exposées par l’API Rest de ce site. Prenons un autre exemple fictif pour mieux comprendre :

facebook.com // Page d'accueil de Facebook
facebook.com/profil // Ma page de profil sur Facebook
facebook.com/api // Page d'accueil de l'API Rest de Facebook
facebook.com/api/users // URL de l'API Rest de Facebook permettant de récupérer tous les utilisateurs. (Ne faites jamais ça !)
facebook.com/api/publications // URL de l'API Rest de Facebook permettant de récupérer toutes les publications, qui sont un autre type de ressource proposée par Facebook.

Comme vous pouvez le constater, le site de Facebook expose à la fois une application web publique, que tout le monde connaît plus ou moins, et une API Rest.

Cette API Rest est elle-même composée de plusieurs ressources, comme les utilisateurs ou les publications, afin de permettre à d’autres applications d’utiliser les données de Facebook.

Si vous avez compris ce principe, c’est un immense pas en avant. Je vous propose de voir une dernière distinction concernant les ressources, ce sont les ressources plurielles et singulières. Ce n’est pas bien méchant, regardez plutôt, si nous reprenons notre exemple de pokémons :

my-web-app.com/api/pokemons // Expose tous les pokémons
my-web-app.com/api/pokemon/1 // Expose le pokémon avec l'identifiant n°1
my-web-app.com/api/pokemons/pikachu // Expose le pokémon avec le nom "pikachu"

Nous avons donc le moyen d’exposer deux types de ressources :

  • Les ressources plurielles : C’est un ensemble de plusieurs ressources. On parle de collections. Par exemple, pour ajouter un pokémon sur notre API Rest, on utilisera une collection. Vous pouvez voir une collection comme un tableau d’objets.
  • Les ressources singulières : C’est une ressource exposée « toute seule ». Par exemple, pour modifier ou supprimer un pokémon précis sur notre API Rest, on passera par une ressource singulière, car on ne veut pas appliquer la modification à tous nos pokémons. Vous pouvez voir ce type de ressource comme un simple objet.

Aussi, je ne sais pas si vous avez fait attention, mais nous pouvons passer des paramètres à notre API Rest. Reprenons les deux urls précédentes :

my-web-app.com/api/pokemon/1 // Expose le pokémon avec l'identifiant n°1
my-web-app.com/api/pokemons/pikachu // Expose le pokémon avec le nom "pikachu"

Eh bien pour mettre en place ces urls côté serveur, il faudra que nous définissions des paramètres à nos requêtes :

my-web-app.com/api/pokemon/:id // Expose le pokémon avec l'identifiant "id" passé en paramètre
my-web-app.com/api/pokemons/:name // Expose le pokémon avec le nom "name" passé en paramètre

Mais nous verrons comment faire cela le moment venu. 😉

Maintenant, il nous reste à voir comment une application web ou mobile pourra consommer ces fameux endpoints.