Section: Un contrôleur pour REST
| « Utiliser le contrôleur CRUD | ^ Développement d'un module | Faire une redirection » |
− Table des matières
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 à utiliser votre moteur de recherche !
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.
