Documentation de l'API Streamfizz

La plateforme Streamfizz fournis aux développeurs une API d'échange de données permettant de consulter le contenu de la plateforme à distance depuis une adresse web.

Grâce à cette API, les applications sont nombreuses et les possibilités d'intégration décuplées !

Définition

L'API Streamfiiz repose sur une architecure REST (Representational state transfer), modèle applicatif original du Web.

Il repose sur un modèle de ressources identifiées de manière unique par une URI et accédées par un jeu limité de méthodes: GET, POST, PUT, DELETE,...

Un Web Service basé sur l'architecture REST se distingue donc des Web services SOAP ou XML-RPC par une approche orientée ressource par opposition à une approche orientée API objet. Il respecte ainsi parfaitement l'esprit original du Web et est beaucoup plus simple d'approche. Il permet en effet de baser les interactions machine-machine sur le même modèle que les interactions homme-machine.

Dans le modèle REST, chaque ressource de l'application est donc identifiée par une URI unique.

On joue ensuite sur la méthode HTTP pour déterminer le type d'action. Le modèle REST définit les actions suivantes:

Méthode HTTP Action
GET Lit une ressource
POST Insère une ressource
PUT Met à jour une ressource
DELETE Supprime une ressource

Bénéfices

Les bénéfices d'une approche REST par rapport à une approche SOAP ou XML-RPC sont les suivants:

Accès

L'API Streamfizz est disponible à l'adresse suivante :

https://phc.webcastor-hd.fr/index.php/api/[RESSOURCE]

La consultation des données s'effectue au travers d'une URL dont la structure indique l'information que vous demandez :

Ex : https://phc.webcastor-hd.fr/index.php/api/media/cat_id/6/format/xml
Structure : http://[domaine_plateforme]/index.php/api/[ressource]/[parametres]/format/[format_de_sortie]

Ressources disponibles

5 types de ressources sont actuellement disponibles à la consultation :

Ressources disponibles
imageListe les images du système
sonListe les sons du système
vidéoListe les vidéo du système
catListe les vidéo du système
mediaListe tous les médias du système

Ainsi, pour demander la liste des "images" disponibles sur la plateforme pour votre compte utilisateur, l'adresse à contacter sera :

https://phc.webcastor-hd.fr/index.php/api/image

Paramètres

Ci-dessous, la liste des paramètres disponibles pour chaque ressources. Ces paramètre peuvent être utilisés pour filtrer vos résultats. Les paramètres sont à indiquer dans l'URL, à la suite de la ressource demandée sous la forme :

clé/valeur/clé/valeur/...

A completer

Formats de sortie

Le webservice Streamfizz vous autorise à recevoir le contenu généré dans divers langages lui permettant de s'adapter à vos méthodes et vos langages de programmation.

Formats de sortie disponibles :

langageExplicationsSyntaxe d'appel
XMLFormat de sortie par défaut. Le webservice renvoi les résultats sous la forme d'un document XML qui faut ensuite parser. format/xml
JSON Format de sortie pour réutilisation des données en JAVASCRIPT format/json
SERIALISE Les données trouvées sont renvoyées sous la forme d'une chaine de caractères contenant les objets sérialisés. Utilisez la fonction unserialize() de php pour retrouver les valeurs sous la forme d'un tableau. format/serialize
PHP Les données sont retournées sous la forme d'une chaine de caractères contenant une représentation du code PHP généré. Utiliser la fonction eval() de php pour retrouver les valeurs sous la forme d'un tableau. Cette utilisation n'est pas recommandée. format/php
HTML Simple sortie des données sous la forme d'un tableau HTML. format/html
CSV Sortie des données sous la forme d'un fichier CSV dont les champs sont séparés par des points-virgules. format/csv

Notez que si le format de sortie n'est pas spécifié dans l'URL, le format de retour utilisé sera XML. Enfin, le type de format choisi devra être indiqué en fin d'URL après les paramètres de filtre.

Exemple d'utilisation :

https://phc.webcastor-hd.fr/index.php/api/cat/parent_id/2/format/html

Listera toute les catégories dont la catégorie parente possède l'ID 2. Le format de sortie sera HTML.

Exemple d'intégration du WebService

Les web services sont sécurisés par un mécanisme de login / mot de passe correspondant à une authentification basique HTTP. Ainsi, afin de récupérer une réponse du webservice, vous devrez mettre en place un mécanisme d'authentification dans les scripts chargés d'interroger ce dernier.

Récupération des données

Ci-dessous, une des méhodes possible pour lancer une requête au WebService Streamfizz :

<?php /* INFORMATION D'IDENTIFICATION STREAMFIZZ */ $username = 'votre login'; $password = 'votre mot de passe';

/* RECUPERATION DU FICHIER XML */ $curl_handle = curl_init(); curl_setopt($curl_handle, CURLOPT_URL, 'https://phc.webcastor-hd.fr/index.php/api/media/cat_id/1/format/xml'); curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curl_handle, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); curl_setopt($curl_handle, CURLOPT_USERPWD, $username . ':' . $password);

$output = curl_exec($curl_handle);
curl_close($curl_handle);
echo var_dump($output);
?>

Parcourir le XML

Ci-dessous, une proposition de code vous permettant de parcourir les données XML reçues et les transformer en un tableau associatif; plus facilement utilisable en php :

$xml = new XMLReader(); $xml->xml($output); $assoc = xml2assoc($xml); $xml->close(); echo '<pre>'; print_r($assoc); echo '</pre>'; /* FONCTIONS DE TRANSFORMATION DU FICHIER XML EN OBJET PHP */
function xml2assoc($xml) { $assoc = null; while($xml->read()){ switch ($xml->nodeType) { case XMLReader::END_ELEMENT: return $assoc; case XMLReader::ELEMENT: $assoc[$xml->name][] = array('value' => $xml->isEmptyElement ? '' : xml2assoc($xml)); if($xml->hasAttributes){ $el =& $assoc[$xml->name][count($assoc[$xml->name]) - 1]; while($xml->moveToNextAttribute()) $el['attributes'][$xml->name] = $xml->value; } break; case XMLReader::TEXT: case XMLReader::CDATA: $assoc .= $xml->value; } } return $assoc; }