Troisième et dernière partie sur l'utilisation de l'API du projet-ode. Nous avons vu comment enregistrer un événement dans la base de donnée du projet-ode. Puis comment on pouvait le modifier.
Il existe aussi une méthode pour supprimer un événement. Toutefois, si une manifestation doit être annulée, je pense qu'il est préférable de modifier l'événement (comme on l'a vu dans la partie 2) afin que les ré-utilisateurs des données puissent récupérer l'information et la répercuter sur leurs publications.
Autre cas de figure : si vous ré-utilisez le même enregistrement d'un événement d'une année sur l'autre, il faudra veiller à supprimer l'enregistrement correspondant dans la table Table_projet_ode dès que celui-ci sera expiré.

À ce propos –petit détail technique– si l'on veut que les ré-utilisateurs puissent suivre les modifications d'un événement, il faut leur fournir un moyen de comparer les dates de modification (ce que j'ai appelé LastMod voir ici). Il serait souhaitable que l'API renvoie ce type de champ quand on accède un événement.

Intégration dans un site web

Vous avez vu les principales commandes, reste maintenant à voir comment intégrer ces opérations dans un site existant.
Comme on l'a vu dans la partie 1, la liste des champs possibles est assez étendue. Tout n'est pas forcément applicable à tous les cas de figure, cependant l'intérêt du projet-ode sera d'autant plus grand que les ré-utilisateurs pourront récupérer un maximum d'informations.
Certaines informations seront toujours les mêmes – tout ce qui concerne l'adresse, les contacts – d'autres sont dépendantes de l'événement; typiquement : les dates. Toutes ces informations sont stockées et organisées dont votre DB. Pour publier une information, le processus consiste à alors à “requêter” (oui, c'est comme ça qu'on dit !) cette DB pour récupérer les enregistrements qui doivent être publiés sur le projet-ode, s'assurer de la validité des champs, les formater et préparer leur encodage pour être envoyés à l'API du projet-ode.

Valider et formater

Une des informations importantes ce sont les dates. Vous pouvez voir sur la page du projet-ode que l'API attend un format bien particulier (format ISO: YYYY-MM-DDThh:mm:ss) qui, en général, n'est pas exactement celui stocké en DB. Mais encore une fois le code –PHP, par exemple– sait faire.  
À partir de là préparer les données pour l'envoi revient à faire une liste de la forme :

name: nom_du_champ, value: contenu_du_champ 

puis empaqueter cette liste dans un gabarit et encoder le tout au format json. Un exemple de code[1]

Automatiser

Comment s'assurer que l'on puisse récupérer tous les événements enregistrés dans la DB qui doivent être publiés et uniquement ceux-là ?
Les ordinateurs font cela très bien : on leur demande de requêter la DB –toutes les heures par exemple– pour voir si un événement a été enregistré ou modifié.
Et comment le sait-on ? Avec la technique vu plus haut : comparer l'heure de dernière modification dans votre DB. Si elle n'a pas changé depuis la dernière exécution de notre tâche c'est qu'il n'y a pas de nouvel événement à traiter. L'ordinateur se rendort jusqu'à l'heure suivante.

Pour conclure

J'espère que ce rapide tour d'horizon de l'API du projet-ode vous aura permis de vous faire une idée de sa mise en application.
Je me suis efforcé de tester la plupart des fonctionnalités du projet et j'ai remonté au développeur les problèmes rencontrés. Mes suggestions pour l'amélioration de l'API serait de rajouter quelques champs :

• date de dernière modification de la ressource
• url de la page web de l'événement
• latitude du lieu de l'événement
• longitude du lieu
• horaires du lieu (pour les événements sur une durée)

Vous avez d'autres questions concernant l'installation sur votre site web ?
Contactez-moi !
Vous voulez en savoir plus ce que je fais ? C'est sur cette page.
Ou sur twitter @pl4n3th

Exemple de code pour préparer et envoyer un événement ↑

<?php
use Buzz\Client\Curl;
class plhOdeWrapper
{
    /* l'url d'accès à l'API de projet-ode */
    private $api_url = 'https://projet-ode.org/api/v1/events';

    /* la clé d'API  */
    private $api_key = 'Token ma_cle_api';

    private $browser;
    private $headers;
    private $event;

    public function __construct()
    {
        $client = new Curl();
        $client->setVerifyPeer(false);
        $this->headers = array(
            'Authorization' => $this->api_key,
            'Content-Type' => 'application/vnd.collection+json'
        );
        $this->browser = new Buzz\Browser($client);
    }

    /* cette commande va déclencher les opérations */
    public function eventPost()
    {
        $this->event = getEventFromDB();
        $this->setDate();
        $json = $this->collectionFormat();

        $this->postToOde ($json);                        
    }

    private function getEventFromDB()
    {
        /* requête la base de données et renvoie un enregistrement */
    }

    /* ici on transforme les dates issues de la base de données dans le bon format */
    private function setDate()
    {
        $date = new DateTime;

        $date->setTimestamp($this->event['uPosted']);
        $this->event['start_time'] = $date->format(DateTime::ISO8601);

        $date->setTimestamp($this->event['uExpires']);
        $this->event['end_time'] = $date->format(DateTime::ISO8601);

        unset ($this->event['uPosted']);
        unset ($this->event['uExpires']);
    }

    private function collectionFormat () 
    {    
        /* constitution de la liste de champs avec leur valeur */
        $data = array();
        foreach ($this->event as $name => $value) {
            $data[] = array(
                'name' => $name ,
                'value' => $value
            );
        }

        /* on empaquête la liste dans le gabarit */
        $pay_load = array(
            'template' => array(
                'data' => $data
            )
        );

        /* et on retourne le tout au format json */
        return json_encode($pay_load);
    }

    /* c'est ici qu'on envoie le paquet à projet-ode */
    private function postToOde ($pay_load) 
    {
        $response = $this->browser->post(
                        $this->api_url,
                        $this->headers,
                        $pay_load
                    );
        $content = json_decode($response->getContent());    
    }
}