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

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.

Classe Article

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.

• 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

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.

• 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

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

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.

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.