Raccourcis : Contenu - rubriques - sous rubriques
EN FR

La technique REST consiste à utiliser les fonctionnalités du protocole HTTP pour manipuler une ressource. En effet, il existe les méthodes POST et GET que vous connaissez, mais il existe aussi les méthodes PUT et DELETE par exemple. Ainsi, pour effectuer une création, un affichage, un effacement d'une ressource, plutôt que d'avoir plusieurs URLs spécifiques pour faire cela, il y a une seule URL, et on utilise le champ "method" de HTTP pour indiquer l'action à effectuer.

Pour en savoir plus sur les principes de REST, il existe pas mal d'explications sur le web. N'hésitez pas à googler !

Voyons maintenant comment faire du REST dans Jelix.

Le contrôleur

Nous avons vu qu'il existe 4 méthodes GET, POST, DELETE, PUT dans le protocole HTTP. Il faut implémenter donc 4 méthodes pour chacune d'elles dans un contrôleur.

Vous devez réaliser un contrôleur qui va implémenter l'interface jIRestController. Ce contrôleur ne pourra être utilisé que pour faire du REST. Vous ne pourrez donc pas réaliser des méthodes pour des actions supplémentaires, autres que les quatre imposées par l'interface jIRestController :



class exempleCtrl extends jController implements jIRestController {

   function get(){

   }

   function post(){

   }

   function put(){

   }

   function delete(){

   }
}

Dans ces méthodes, vous développez vos actions comme à l'accoutumée, en respectant la signification de ces méthodes. En général, GET doit correspondre à un affichage d'une ressource, POST à sa création, PUT à sa modification, et DELETE à sa suppression.

Note : il est indispensable de déclarer que vous implémentez l'interface jIRestController. C'est en effet en analysant le contrôleur que Jelix sait si vous faites du REST ou pas, ce qui change son comportement interne.

Appel d'une action d'un contrôleur REST

Comme la nature de l'action est indiquée dans la méthode HTTP, de l'extérieur vous n'avez en fait qu'une seule url, donc qu'une seule action. C'est le type de la méthode HTTP indiquée dans la requête HTTP qui indiquera à Jelix d'appeler l'une des 4 méthodes du contrôleur.

Aussi, quand vous voulez récupérer avec jUrl l'url de l'action qui correspond à votre contrôleur REST, vous ne devez indiquer que le module et le nom du contrôleur, et ne pas mettre donc le nom d'une méthode.

Ainsi, l'action qui permet d'appeler les méthodes contrôleur de l'exemple, est "leModule~exemple:" (si le module est "leModule"). Notez qu'il faut mettre un ":" pour indiquer que l'on indique bien le nom du contrôleur, et non le nom d'une méthode.

Avec l'url obtenu par jUrl::get("leModule~exemple:"), vous pouvez alors appeler dans vos scripts javascripts, via xmlHttpRequest par exemple, l'une des quatre méthodes du contrôleur, simplement en indiquant à xmlHttpRequest que vous voulez utiliser GET, POST, DELETE ou PUT.

Note

Vous pouvez bien sûr faire du REST avec un contrôleur classique, en testant dans votre action, la valeur de $_SERVER['REQUEST_METHOD'] qui indique le type de la méthode HTTP. Mais c'est peut-être moins "sexy" que d'utiliser le procédé indiqué dans cette page pour implémenter du REST ;-)

Récupérer les paramètres de requêtes

Comme dans n'importe quel contrôleur, vous récupérez les paramètres avec la méthode param() en indiquant le nom du paramètre, en particulier pour les méthodes POST et GET, comme à l'habitude.

Bien sûr, pour POST ou PUT, param() ne fonctionne que si les paramètres sont envoyés sous les types de format "multipart/form-data", "application/json" ou "application/x-www-url-encoded" (ce qui est le cas dans la majorité des cas avec POST).

Voir la section sur la récupération des paramètres pour connaître toutes les possibilités.