larlet-fr-david/david/biologeek/archives/20070807-une-solution-pour-faciliter-la-conception-d-applications-web-restful-avec-django/article.md

title:      Une solution pour faciliter la conception d'applications web RESTful avec Django
slug:       une-solution-pour-faciliter-la-conception-d-applications-web-restful-avec-django
date:       2007-08-07 01:03:11
type:       post
vignette:   images/logos/django.png
contextual_title1:  ★ Architecture web moderne et agile
contextual_url1:    20080604-architecture-web-moderne-et-agile
contextual_title2:  ★ De l'OpenData au LinkedData : exemple de nosdonnees.fr
contextual_url2:    20101130-de-lopendata-au-linkeddata-exemple-de-nosdonneesfr
contextual_title3:  ★ Pourquoi Python et Django
contextual_url3:    20091211-pourquoi-python-et-django

<p>Voila la solution à laquelle je suis arrivé après avoir testé les solutions existantes&nbsp;: <a href="http://code.google.com/p/djangocollection/">django collection</a>, <a href="http://code.google.com/p/django-crudapi/">django crudapi</a> et <a href="http://code.google.com/p/django-restful-model-views/">django restful model views</a>. J'attends beaucoup du <a href="http://code.google.com/p/django-rest-interface/"><abbr title="Google Summer of Code">GSoC</abbr> consacré à l'inclusion native de REST dans Django</a> et les choses vont dans le bon sens de ce côté là mais j'avais besoin d'une solution <em>maintenant</em>. Enfin notez bien le <strong>une</strong> dans le titre qui est très important, il y a énormément d'interprétations de l'architecture <abbr title="Representational State Transfer">REST</abbr>, cette implémentation essaye de s'inspirer de celle définie dans le livre RESTful Web Services&nbsp;: l'<a href="https://larlet.fr/david/biologeek/archives/20070629-architecture-orientee-ressource-pour-faire-des-services-web-restful/">architecture orientée ressource (ROA)</a>.</p>

<h2>Objectif ressource</h2>


<p><strong>Le but principal de cette solution est de simplifier le développement de l'accès à vos ressources. Pour cela une classe générique s'occupe de dispatcher votre requête dans la bonne méthode en fonction du verbe HTTP</strong>. Dans le cas d'une application authentifiée, vous pouvez contrôler les accès aux ressources en fonction des permissions de Django. Enfin la notion d'annulation  a été incluse car j'apprécie cette approche (cf. en fin de billet).</p>


<h2>Préparons le terrain</h2>


<p>La première chose à faire est d'utiliser le middleware permettant d'effectuer de fausses requêtes HTTP PUT et DELETE à partir d'un navigateur (ce qui n'est pas possible actuellement)&nbsp;:</p>


<pre>_SUPPORTED_TRANSFORMS = ['PUT', 'DELETE']
_MIDDLEWARE_KEY = '_method'

class HttpMethodsMiddleware(object):
    def process_request(self, request):
        if request.POST and _MIDDLEWARE_KEY in request.POST:
            if request.POST[_MIDDLEWARE_KEY].upper() in _SUPPORTED_TRANSFORMS:
                request.method = request.POST[_MIDDLEWARE_KEY].upper()
        return None</pre>


<p>Cela permet de passer de convertir le verbe POST en PUT ou DELETE en fonction de l'argument <strong>_method</strong> (généralement caché dans un formulaire).</p>


<p>Les permissions par défaut de Django n'incluent pas la notion d'affichage, il est donc nécessaire d'ajouter cette permission à tous vos modèles. Comme tout ce qui est long et fastidieux avec Django, il existe une solution élégante utilisant les <em>signals</em> pour automatiser tout ça&nbsp;:</p>


<pre>def create_retrieve_permissions(app, created_models, verbosity):
    app_models = get_models(app)
    for klass in app_models:
        ctype = ContentType.objects.get_for_model(klass)
        codename = _get_permission_codename('retrieve', klass._meta)
        name = 'Can %s %s' % ('retrieve', klass._meta.verbose_name)
        p, created = Permission.objects.get_or_create(codename=codename,
            content_type__pk=ctype.id,
            defaults={'name': name, 'content_type': ctype})
        if created and verbosity &gt;= 2:
            print "Adding permission '%s'" % p

dispatcher.connect(create_retrieve_permissions, signal=signals.post_syncdb)</pre>


<p>La permission est créée à chaque fin de <strong>syncdb</strong> pour l'ensemble des modèles existants.</p>


<h2>Passons aux choses sérieuses</h2>


<p>Je ne vais pas trop coller de code ici, vous le retrouverez commenté dans le paquet. Je vais plus expliquer les concepts pour comprendre comment l'utiliser.</p>


<p>Nous allons implémenter une todo liste basique permettant d'exploiter les différentes fonctionnalités développées. Nos URI devront avoir le modèle suivant (conformément au <a href="http://bitworking.org/news/wsgicollection">design définit par Joe Gregorio</a>)&nbsp;:</p>


<pre>/{model}/{id};{noun}</pre>



<p>Vous savez qu'une URL se construit avec Django de la façon suivante&nbsp;:</p>


<pre>urlpatterns = patterns('',
    (expression régulière, fonction de la vue),
)</pre>


<p>L'idée ici est de passer non pas une fonction à votre pattern mais une classe, ou plus précisément une instance de classe. En instanciant cette classe, vous allez appeler la méthode __call__ de la classe (ça c'est du python) qui va faire tout le travail de redirection vers la bonne méthode de la classe en fonction du verbe HTTP de la requête.</p>


<p>On va donc avoir une définition des URL qui va ressembler à ça&nbsp;:</p>


<pre>urlpatterns = patterns('',
    (r'^/todos/(?:(?P&lt;id&gt;\d+)/?)?(?:;(?P&lt;noun&gt;\w+))?/?$',
        TodoCollection()),
)</pre>


<p>Ok, maintenant voyons voir ce qui se cache dans TodoCollection&nbsp;:</p>


<pre>class TodoCollection(GenericCollection):
    def __call__(self, request, **kw):
        return super(TodoCollection, self).__call__(request, 'todo', 'todo', **kw)</pre>

<p>TodoCollection hérite de GenericCollection qui est la classe de base permettant d'automatiser l'accès aux ressources. Seule la fonction __call__ doit être réécrite pour tenir compte du nom de l'application et du modèle (vous pouvez encore plus automatiser en passant ces argument dans l'URL ou dans un dictionnaire mais nous verrons par la suite que cette nouvelle classe peut être utile pour y placer les fonction spécifiques à nos ressources).</p>


<p>Arrivé dans GenericCollection, la requête va être redirigée vers la fonction appropriée selon les équivalences suivantes (notez le caractère facultatif des paramètres <em>id</em> et <em>noun</em> dans l'expression régulière)&nbsp;:</p>

<ul>
<li>si c'est un GET sans id, redirection vers la fonction <strong>list</strong>&nbsp;;</li>
<li>si c'est un POST, redirection vers la fonction <strong>create</strong>&nbsp;;</li>
<li>si c'est un GET avec id, redirection vers la fonction <strong>retrieve</strong>&nbsp;;</li>
<li>si c'est un PUT avec id, redirection vers la fonction <strong>update</strong>&nbsp;;</li>
<li>si c'est un DELETE avec id, redirection vers la fonction <strong>delete</strong>&nbsp;;</li>
</ul>

<p>Dans le cas où il y a argument <strong>noun</strong>, la redirection s'effectue vers la fonction <strong>verbeHTTP_noun</strong> ce qui permet d'ajouter des vues si vous avez des besoins spécifiques, typiquement pour afficher un formulaire de mise à jour d'une ressource vous devrez pointer vers une URI de ce type&nbsp;:</p>


<p>/todos/{id};update_form</p>


<p>qui redirigera vers la fonction <strong>get_update_form</strong> de votre classe Collection.</p>


<p>Vous avez compris le principe&nbsp;? Étudions maintenant une fonctionnalité en particulier (attention la suite est un peu brutale, pour un vrai exemple je vous recommande celui du paquet).</p>


<h2>Trêve de confirmation</h2>


<p>Un <a href="http://www.alistapart.com/articles/neveruseawarning">récent article sur A List Apart</a> évoquait les avantages d'une annulation possible d'une action par rapport à une confirmation préalable. Il est vrai que les messages de confirmation sont toujours frustrants et sont de toute manière tellement banalisés aujourd'hui qu'ils ne sont plus lus par l'utilisateur.</p>


<p>Suite à cet article, une <a href="http://simonwillison.net/2007/Jul/17/undo/">discussion intéressante sur son implémentation dans Django</a> chez Simon Willison a aboutit à <a href="http://nathanostgard.com/archives/2007/7/18/undelete-in-django/">son implémentation</a> chez Nathan Ostgard m'ont permis d'intégrer cette fonctionnalité à moindre coût.</p>


<p>Elle impose tout de même d'ajouter un champ, deux fonctions et un manager à votre modèle&nbsp;:</p>


<pre>class TrashManager(models.Manager):
    def get_query_set(self):
        return super(TrashManager, self) \
            .get_query_set().filter(trashed_at__isnull=True)

    def get_trashed(self):
        return super(TrashManager, self) \
            .get_query_set().filter(trashed_at__isnull=False)


class Todo(models.Model):
    [...]
    trashed_at = models.DateTimeField(blank=True, null=True, editable=False)
    objects = TrashManager()

    def trash(self):
        self.trashed_at = datetime.now()
        self.save()

    def restore(self):
        self.trashed_at = None
        self.save()</pre>

<p>Cela vous permet de placer les ressources «&nbsp;supprimées » dans une corbeille temporaire permettant leur récupération après suppression malencontreuse (l'effet Ooops!). La base doit ensuite être régulièrement purgée ce qui est simplifié par l'accès aux éléments de la corbeille avec le manager&nbsp;:</p>


<pre>model.objects.get_trashed()</pre>


<p>Voyons maintenant ce que ça donne avec ma solution. Ce cas est très particulier et c'est intéressant car on va accéder aux limites de la solution justement. En effet, la suppression doit normalement être effectuée via un DELETE mais dans notre cas une mise dans la corbeille signifie une modification de la ressource et donc un PUT. Cruel dilemme&nbsp;!</p>


<p>Nous allons devoir créer une nouvelle méthode à notre classe gérant ce cas particulier, celle-ci sera accessible via&nbsp;:</p>


<pre>/todos/{id};trash</pre>


<p>qui redirigera vers la fonction (simplifiée pour l'exemple)&nbsp;:</p>


<pre>    def put_trash(self):
        self.item_instance.trash()
        message = _("Item trashed successfully. \
            &lt;a href=\"%s;recover?_method=put\" title=\"\"&gt;Restore?&lt;/a&gt; \
            " % self.id)
        self.request.user.message_set.create(message=message)</pre>


<p>Cette fonction est bien accessible via un PUT ce qui reste correct (si un client à ce service web est implémenté, il utilisera directement DELETE sans avoir besoin de confirmation). Un lien est ensuite proposé à l'utilisateur pour annuler cette «&nbsp;suppression » qui lui est beaucoup moins RESTful...</p>


<p>En effet, pour simplifier la récupération j'ai préféré placer un lien (ce qui n'est pas forcément conforme aux règles d'ergonomie qui stipulent qu'une donnée ne doit être modifiée qu'à travers un formulaire, d'où l'aspect si <del>hideux</del> reconnaissable des boutons de formulaires). Du coup je suis obligé de passer la méthode en argument pour faire un faux PUT, histoire d'être tout de même cohérent au niveau de ma classe&nbsp;:</p>


<pre>    def put_recover(self):
        self.model.objects.get_trashed().get(pk=self.id).restore()
        message = _("Item recovered successfully.")
        self.request.user.message_set.create(message=message)
        return HttpResponseRedirect('.')</pre>


<p>Ouf, on y est tout de même arrivé (il faut modifier le middleware du début pour qu'il utilise request.REQUEST et non request.POST si vous souhaitez faire du faux PUT avec du GET).</p>


<h2>Conclusion et évolutions</h2>


<p><strong>La solution permettant de gérer des collections génériques est satisfaisante (même s'il manque encore quelques fonctionnalités) et constitue un bon exemple de ce qui peut être fait à la fois avec Django et avec REST et c'est plus dans cette optique que je la publie.</strong></p>


<p>Il est parfois difficile de s'en tenir à une architecture RESTful dans les cas extrêmes et certains impératifs peuvent nécessiter quelques entorses aux règles que vous vous êtes fixé. Le plus important est d'en être conscient et d'assumer ses choix en connaissance de cause. Dans mon exemple sur l'annulation je sais très bien que c'est une fonctionnalité qui ne sera pas utilisée par un programme tiers.</p>


<p>Enfin deux mots sur ce qu'il resterait à implémenter (je reste dans le conditionnel car je pense que le GSoC permettra prochainement de faire la même chose en mieux, du moins je l'espère et je participe en ce sens)&nbsp;:</p>

<ul>
<li>Gérer différents formats de représentation des ressources (json, xml, etc).</li>
<li>Gérer les différentes erreurs possibles avec les codes appropriés (403, etc).</li>
<li>Rendre possible l'utilisation d'une classe avec url_reverse, notamment pour utiliser le tag {% url %} dans les templates.</li>
</ul>

<p>En attendant, vous pouvez toujours <a href="#">télécharger la version actuelle</a> et jouer avec&nbsp;! (n'oubliez pas d'ajouter le dossier à votre $PYTHONPATH...)</p>