Séances 4 et 5 : API et manipulation de ressource
=================================================

.. include:: common.rst.inc
.. ifslides::

   .. include:: credits.rst.inc

Notion d'API Web
++++++++++++++++

Définition
----------

En programmation classique,
on appelle API (*Application Programming Interface*)
l'ensemble des classes et des fonctions que propose une bibliothèque,
dédiée à la manipulation d'une certaine catégorie d'objets.

Une API Web est
l'ensemble des requêtes HTTP que propose un serveur,
permettant la manipulation des ressources de ce serveur.


Autres verbes
+++++++++++++

``PUT``
-------

Ce verbe sert à envoyer un contenu à une ressource pour *modifier* son état.
En général,
le contenu du ``PUT`` correspond à une version modifiée du contenu retourné par un précédent ``GET``.

``DELETE``
----------

Ce verbe sert à supprimer une ressource du serveur.


Votre travail
+++++++++++++

Votre travail
-------------

En vous appuyant sur `la documentation de l'API du blog éphémère`__,
vous devez écrire deux classes, permettant d'accéder à ce blog.

En d'autre terme,
vous devez proposer une API Java qui donne accès à l'API Web du blog éphémère.

__ https://liris-ktbs01.insa-lyon.fr:8000/blogephem/apidoc


Classe ``Article``
------------------

.. code-block:: java

    public class Article {
        public Article(URL url) {}
        protected void refresh() {}
        protected void update() {}
        public URL getURL() {}
        public String getTitle() {}
        public String getBody() {}
        public String getDate() {}
        public void setTitle(String newTitle) {}
        public void setBody(String newBody) {}
        public void delete() {}
    }

* Le « constructeur » ne crée pas un nouvel article ;
  il crée un objet Java qui permet d'accéder à l'article **pré-existant** sur le Web.

* C'est la méthode ``Blog.createArticle`` (cf. ci-aprèsà
  qui permettra de créer un nouvel article.

.. nextslide::

* La méthode protégée ``refresh`` est celle qui effectue la requête ``GET``
  pour récupérer les données XML de l'article.
  Elle doit être appelée à chaque fois que c'est nécessaire :

  + ni trop (pas la peine de faire une requête HTTP inutile),
  + ni trop peu (pensez bien que l'article peut-être modifié sur le serveur
    par un autre programme, y compris pendant que vous l'utilisez).

* La méthode protégée ``update`` est celle qui effectue la requête ``PUT``
  pour mettre à jour les données XML de l'article.
  Elle doit être appelée à chaque fois que c'est nécessaire.

Classe ``Blog``
---------------

.. code-block:: java

    public class Blog {
        public Blog(URL url) {}
        public URL getURL() {}
        public Iterable<Article> iterArticles() {}
        public Iterable<Article> iterArticles(String filtre) {}
        public Article createArticle(String title, String body) {}
    }

* Ici encore,
  le « constructeur » ne sert **pas** à créer le blog éphémère
  (qui évidemment existe déjà)
  mais à créer un *objet Java* qui permet d'interagir avec le blog.

* Le constructeur prend une URL en paramètre,
  car il peut exister d'autres blogs compatibles avec cette API Web.

.. nextslide::

* La méthode ``createArticle`` pourra s'inspirer de ce que vous avez fait à la séance précédente,
  mais vous devez poster du XML plutôt que des données de formulaire.


Analyser du XML en Java
```````````````````````

.. code-block:: java

    URL url; // l'URL que vous venez de requêter
    InputStream cxIs; // le flux contenant la réponse du serveur
    javax.xml.parsers.DocumentBuilder db =
            javax.xml.parsers.DocumentBuilderFactory
                    .newInstance().newDocumentBuilder();
    org.w3c.dom.Document doc = db.parse(cxIs, url.toString());
    org.w3c.dom.NodeList nl = doc.getDocumentElement().getChildNodes();

Sérialiser du XML en Java
`````````````````````````

.. code-block:: java

    org.w3c.dom.Document doc; // le document à sérialiser
    DOMImplementationLS domImplementation =
            (DOMImplementationLS) doc.getImplementation();
    LSSerializer lsSerializer = domImplementation.createLSSerializer();
    lsSerializer.getDomConfig()
            .setParameter("xml-declaration", Boolean.FALSE);
    String xml = lsSerializer.writeToString(doc);


Pour aller plus loin
++++++++++++++++++++

Utilisation des *etags*
-----------------------

Les *etags* (*entity tags*) permettent d'économiser de la bande passante,
tout en garantissant que les données sont à jour.

L'*etag* est une chaîne de caractère associée à la ressource,
qui change à chaque fois que la ressource est modifiée
(une espèce de « numéro de série »).

Le serveur fournit l'*etag* de la ressource dans l'en-tête ``Etag``.
Lors de la première requêre ``GET`` qu'il fait à une ressource,
le client mémorise cet *etag*.

.. nextslide::

Lors des requêtes ``GET`` suivantes,
le client fournit l'*etag* dans l'en-tête ``If-None-Match``.

* Si la ressource n'a pas été modifiée,
  le serveur répond avec le code ``304 Not modified``
  sans contenu (et économise ainsi du temps et de la bande passante).

* Si la ressource a été modifiée,
  le serveur répond normalement avec le code ``200 OK``
  avec le nouveau contenu et le nouvel *etag*.

NB: les *etags* participent, avec d'autres en-têtes,
à la gestion des `caches <cache>`:doc:.