larlet-fr-david/david/biologeek/archives/20070501-developper-une-application-restful-avec-django/article.md

title:      ★ Développer une application RESTful avec Django
slug:       developper-une-application-restful-avec-django
date:       2007-05-01 19:50:52
type:       post
vignette:   images/logos/django.png
contextual_title1:  Une solution pour faciliter la conception d'applications web RESTful avec Django
contextual_url1:    20070807-une-solution-pour-faciliter-la-conception-d-applications-web-restful-avec-django
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>Après vous avoir expliqué <a href="https://larlet.fr/david/biologeek/archives/20070413-pour-ne-plus-etre-en-rest-comprendre-cette-architecture/">la théorie sur l'architecture <abbr title="REpresentational State Transfer">REST</abbr></a>, rien de vaut un exemple concret pour bien comprendre le mécanisme. J'ai longtemps hésité entre la classique todolist et un agrégateur pour l'exemple mais j'ai finalement opté pour ce dernier en souvenir d'<a href="https://larlet.fr/david/biologeek/archives/20050820-votre-aggregateur-manquerait-il-de-fonctionnalites/">un projet</a> et pour <a href="https://fluffy.web0.eu/">en aider un autre</a> qui va révolutionner votre notion de l'agrégation (ce sont <a href="http://planet.inertie.org/">eux qui le disent</a> en tout cas...).</p>

<p>Pour commencer un petit avertissement&nbsp;:</p>
<ul>
<li>cet exemple est très basique et ne développe ni toutes les possibilités de <abbr title="REpresentational State Transfer">REST</abbr>, ni toutes les fonctionnalités d'un agrégateur. <strong>Je souhaite juste montrer une implémentation possible avec Django de l'usage des verbes <abbr title="HyperText Transfer Protocol">HTTP</abbr></strong> (GET, POST, PUT et DELETE)&nbsp;;</li>
<li>nous allons nous intéresser aux fils <abbr title="RDF Site Summary">RSS</abbr> et à leur maniement uniquement pour rendre l'exemple relativement générique.</li>
</ul>

<h2>Définition du protocole</h2>


<p>Nous allons suivre les <a href="http://bitworking.org/news/How_to_create_a_REST_Protocol">4 questions à se poser pour concevoir un protocole REST</a> énoncées par Joe Gregorio&nbsp;:</p>


<h3>Quelles sont les <abbr title="Universal Resource Identifier">URI</abbr>&nbsp;?</h3>


<p>Compte-tenu de l'avertissement, on ne s'intéresse qu'aux ressources de type flux RSS, elles sont donc très simples à trouver&nbsp;:</p>

<ul>
<li>/feeds/ pour la liste des items&nbsp;;</li>
<li>/feeds/id/ pour un seul item.</li>
</ul>

<p>Nous verrons qu'il est possible d'en ajouter par la suite.</p>


<h3>Quels sont les formats&nbsp;?</h3>


<p>Nous allons pour cet exemple nous limiter au <abbr title="HyperText Markup Language">HTML</abbr> mais il serait bien sûr intéressant de supporter <acronym>ATOM</abbr>, etc.</p>


<h3>Quelles sont les méthodes supportées par chaque URI&nbsp;?</h3>


<p>Pour /feeds/, il faut supporter les méthodes&nbsp;:</p>

<ul>
<li>GET&nbsp;: pour récupérer la liste des items&nbsp;;</li>
<li>POST&nbsp;: pour ajouter un nouvel item.</li>
</ul>

<p>Pour /feed/id/, il faut supporter les méthodes&nbsp;:</p>

<ul>
<li>GET&nbsp;: pour afficher l'item&nbsp;;</li>
<li>PUT&nbsp;: pour mettre à jour l'item&nbsp;;</li>
<li>DELETE&nbsp;: pour supprimer l'item.</li>
</ul>

<p>Voila qui est suffisant pour le moment.</p>


<h3>Quels sont les indicateurs d'état (status codes) à renvoyer&nbsp;?</h3>


<p>Pour ne pas compliquer les choses, on va laisser ça partiellement de côté pour le moment. On ne va gérer que les erreurs 404 lorsque l'on essaye de modifier/supprimer un item non connu.</p>


<h2>Implémentation avec Django</h2>


<h3>Modèle de données</h3>


<p>Le modèle le plus simple que l'on peut avoir afin présenter un exemple fonctionnel est le suivant&nbsp;:</p>


<pre>class Feed(models.Model):
    title = models.CharField(maxlength=200)
    url = models.URLField()
    state = models.BooleanField()</pre>


<p>Le titre pourra être renseigné à partir de l'URL et state permet de d'activer/désactiver un flux au besoin.</p>


<h3>URL</h3>


<p>Comme convenu dans le protocole, nous avons les deux ressources&nbsp;:</p>


<pre>from views import index, item

urlpatterns = patterns('',
    (r'^/feeds/$', index),
    (r'^/feeds/(?P&lt;object_id&gt;\d+)/$', item),
)</pre>


<h3>Les vues</h3>


<p>C'est là que ça devient intéressant :-). Nous avons deux vues à définir&nbsp;: <em>index</em> et <em>item</em> qui implémentent les méthodes décrites dans le protocole. Commençons avec index&nbsp;:</p>


<pre>from models import Feed

def index(request):
    FeedForm = forms.form_for_model(Feed)

    #POST
    if request.method == 'POST':
        form = FeedForm(request.POST)
        if form.is_valid():
            data = form.clean_data
            feed = Feed()
            feed.title = data['title']
            feed.url = data['url']
            feed.state = data['state']
            feed.save()

    #GET
    return render_to_response("feed/index.html",
        {
            'feed_list': Feed.objects.all(),
            'form': FeedForm()
        })</pre>


<p>On commence par créer un formulaire à partir du modèle Feed qui va nous servir par la suite. Pour cette vue, il faut traiter les deux verbes GET et POST. Dans le cas de POST, on remplit le formulaire préalablement créé avec les donnée issues de la requête et on vérifie ensuite son intégrité. Si tout va bien, on crée la nouvelle ressource. Dans le cas de GET, on affiche la liste des items ainsi qu'un formulaire pour compléter la liste. Voici le template associé&nbsp;:</p>


<pre>{% if feed_list %}
    &lt;ul&gt;
    {% for feed in feed_list %}
        &lt;li&gt;&lt;a href="{{ feed.get_absolute_url }}"&gt;{{ feed.title }}&lt;/a&gt;&lt;/li&gt;
    {% endfor %}
    &lt;/ul&gt;
{% endif %}
&lt;form action="." method="post"&gt;
    &lt;table&gt;{{ form }}&lt;/table&gt;
    &lt;input type="submit" class="send" name="send" value="Ajouter" /&gt;
&lt;/form&gt;</pre>


<p>Je ne pense pas qu'il y ait besoin de décrire ce qu'il se passe ici, le langage de template de django est assez explicite. Chaque ressource est accessible via son URL qui permet d'accéder à la vue item&nbsp;:</p>


<pre>def item(request, object_id):
    feed = get_object_or_404(Feed, id = object_id)
    FeedForm = forms.form_for_model(Feed)

    # PUT
    if request.method == 'PUT':
        form = FeedForm(request.POST)
        if form.is_valid():
            data = form.clean_data
            feed.title = data['title']
            feed.url = data['url']
            feed.state = data['state']
            feed.save()

    # DELETE
    elif request.method == 'DELETE':
        feed.delete()
        return HttpResponseRedirect('/feeds/')

    # GET
    else:
        form = FeedForm(initial={
                    'title' : feed.title,
                    'url' : feed.url,
                    'state' : feed.state,
                    })

    return render_to_response("feed/item.html",
        { 'feed': feed, 'form': form })</pre>


<p>Considérant la ressource, on peut grâce à cette vue, soit l'afficher (traitement de POST, le formulaire est pré-rempli), la modifier (traitement de PUT), soit la supprimer (traitement de DELETE, retour à la vue d'index). C'est conforme au protocole.</p>


<p>Attendez, là normalement, si vous avez bien suivi le <a href="https://larlet.fr/david/biologeek/archives/20070413-pour-ne-plus-etre-en-rest-comprendre-cette-architecture/">premier billet consacré à REST</a>, vous devez faire un bond. Bon allez je vous laisse une chance, relisez le code attentivement.</p>


<p>Et oui, <strong>comment est-ce que je peux traiter des PUT et des DELETE alors que le navigateur ne connaît pas ces verbes ?</strong></p>


<p>Il va falloir pour cela définir votre propre middleware django (petit bout de code qui permet de modifier les requêtes à la volée), heureusement le traitement des verbes http a déjà été codé et est <a href="http://www.djangosnippets.org/snippets/174/">disponible sur Django Snippets</a>. Nous n'allons prendre que la partie qui nous intéresse&nbsp;:</p>


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

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


<p>Ok, maintenant vous comprenez mieux comment est-ce que les méthodes PUT et DELETE peuvent être détectées.</p>


<p>Le template associé est le suivant&nbsp;:</p>


<pre>{{ feed.title }} : {{ feed.url }} ({{ feed.state }})
&lt;form action="" method="post"&gt;
    &lt;table&gt;{{ form }}&lt;/table&gt;
    &lt;input type="hidden" name="verb" value="PUT" id="id_verb" /&gt;
    &lt;input type="submit" class="send" name="send" value="Modifier" /&gt;
&lt;/form&gt;
&lt;form action="" method="post"&gt;
    &lt;table&gt;{{ form.as_hidden }}&lt;/table&gt;
    &lt;input type="hidden" name="verb" value="DELETE" id="id_verb" /&gt;
    &lt;input type="submit" class="send" name="send" value="Supprimer" /&gt;
&lt;/form&gt;</pre>


<p>Je commence par afficher les données relatives à la ressource actuelle puis le formulaire de modification. <strong>Je n'oublie pas le champ caché verb qui me permet de spécifier à la vue qu'il s'agit du verbe http PUT</strong> (la seconde partie du middleware de django snippets permet de faire la modification à la volée si vous êtes intéressé). Enfin je crée un bouton de suppression en cachant le formulaire avec <strong>.as_hidden</strong>.</p>


<p>Et voila, <strong>nous avons notre application simpliste basée sur l'architecture REST</strong>. Vous aurez remarqué que l'implémentation avec Django est un peu fastidieuse et c'est beaucoup plus simple avec Ruby on Rails 1.2. Heureusement, un <a href="http://code.google.com/soc/django/appinfo.html?csaid=63138DE89788093">Google Summer of Code est consacré entièrement à ça</a>&nbsp;! Que du bon en perspective.</p>


<h2>Et pour quelques <abbr title="Lines Of Code">LOC</abbr> de plus...</h2>


<h3>Ajouter une page de confirmation</h3>


<p>Il est souvent d'usage de proposer une page de confirmation avant de supprimer une ressource (et heureusement !). Comment faire avec Django&nbsp;?</p>


<p>C'est relativement simple, on commence par ajouter la ligne suivante aux URL&nbsp;:</p>


<pre>(r'^/feeds/(?P&lt;object_id&gt;\d+)/delete/$', delete),</pre>


<p>Il va falloir ensuite créer une vue <em>delete</em> qui va proposer le bouton <em>je suis sûr de vouloir supprimer cette ressource</em>.</p>


<pre>def delete(request, object_id):
    feed = get_object_or_404(Feed, id = object_id)
    FeedForm = forms.form_for_model(Feed)
    
    return render_to_response("feed/delete.html",
        { 'feed': feed, 'form': FeedForm() })</pre>


<p>Le template est le même que la dernière partie du précédent. Il faut d'ailleurs y modifier le lien vers la suppression pour qu'il pointe vers cette page.</p>


<h3>Modifier rapidement des valeurs booléennes</h3>


<p>Ici, c'est un peu expérimental encore et je sais que ce n'est pas vraiment RESTful mais il est souvent intéressant de pouvoir modifier une ressource avec un simple lien sans avoir à créer tout un formulaire pour l'occasion (surtout lorsqu'il y a de nombreux champs avec des contraintes, etc). Par exemple ici, si l'on veut pouvoir modifier l'état du flux <em>à la volée</em>.</p>


<p>Voila la solution à laquelle je suis arrivé.</p>


<p>Dans les URL, je rajoute la ligne suivante&nbsp;:</p>


<pre>(r'^(?P&lt;object_id&gt;\d+)/edit/(?P&lt;boolean_id&gt;[\w-]+)/$',  edit),</pre>


<p>Et la vue ressemble à&nbsp;:</p>


<pre>def edit(request, object_id, boolean_id=None):
    feed = get_object_or_404(Feed, id = object_id)
    FeedForm = forms.form_for_model(Feed)
    if boolean_id is None:
        form = FeedForm(initial={
                     'title' : feed.title,
                     'url' : feed.url,
                     'state' : feed.state,
                     })

        return render_to_response("feed/edit.html", 
            { 'feed': feed, 'form': FeedForm() })
    else:
        if hasattr(feed, boolean_id):
            if getattr(feed, boolean_id):
                setattr(feed, boolean_id, False)
            else:
                setattr(feed, boolean_id, True)
            feed.save()

            return HttpResponseRedirect(feed.get_absolute_url())</pre>


<p>Voila la solution à laquelle je suis arrivé, ça permet de modifier un état d'une ressource feed avec l'URL&nbsp;: /feeds/1/edit/state/ (pour rester dans l'exemple) mais ça prend toute sa puissance lorsqu'il y a de nombreuses valeurs booléennes. Par ailleurs, la vue /edit/ permet d'afficher un formulaire de modification si l'on ne souhaite pas que celui-ci soit présent sur la page de la ressource (c'est la première partie de la vue edit).</p>


<p><strong>Je vous la soumet pour discussion car j'aimerais bien arriver à quelque chose de mieux</strong>. Il faudrait que je regarde comment font les autres frameworks.</p>